dalux-build-api 1.1.3 → 1.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (28) hide show
  1. package/LICENSE +21 -21
  2. package/README.md +365 -365
  3. package/package.json +46 -46
  4. package/src/api/CompaniesApi.js +60 -60
  5. package/src/api/CompanyCatalogApi.js +125 -108
  6. package/src/api/FileAreasApi.js +55 -37
  7. package/src/api/FileRevisionsApi.js +31 -31
  8. package/src/api/FileUploadApi.js +64 -64
  9. package/src/api/FilesApi.js +697 -297
  10. package/src/api/FoldersApi.js +281 -58
  11. package/src/api/FormsApi.js +48 -48
  12. package/src/api/InspectionPlansApi.js +62 -62
  13. package/src/api/ProjectTemplatesApi.js +25 -25
  14. package/src/api/ProjectsApi.js +123 -106
  15. package/src/api/TasksApi.js +178 -161
  16. package/src/api/TestPlansApi.js +59 -59
  17. package/src/api/UsersApi.js +47 -47
  18. package/src/api/VersionSetsApi.js +67 -67
  19. package/src/api/WorkPackagesApi.js +26 -26
  20. package/src/apiClient.js +139 -75
  21. package/src/configuration.js +39 -24
  22. package/src/index.js +128 -92
  23. package/src/utils/errors.js +45 -0
  24. package/src/utils/index.js +26 -0
  25. package/src/utils/pagination.js +82 -0
  26. package/src/utils/pathResolver.js +124 -0
  27. package/src/utils/search.js +61 -0
  28. package/src/utils/validation.js +36 -0
package/README.md CHANGED
@@ -1,365 +1,365 @@
1
- # Dalux Build API
2
-
3
- API clients for the [Dalux Build REST API](https://app.swaggerhub.com/apis-docs/Dalux/DaluxBuild-api/4.14), available in two languages:
4
-
5
- | Language | Location | Documentation |
6
- |---|---|---|
7
- | Node.js | [`/`](.) | See below |
8
- | Python | [`/python`](python/) | [python/README.md](python/README.md) |
9
-
10
- ---
11
-
12
- # Node.js Client
13
-
14
- A lightweight Node.js client for the Dalux Build REST API.
15
-
16
- ## Requirements
17
-
18
- - Node.js 14 or later
19
-
20
- ## Installation
21
-
22
- ```bash
23
- npm install dalux-build-api
24
- ```
25
-
26
- ## Getting Started
27
-
28
- To access the API you need:
29
-
30
- 1. A company-specific **base URL** (obtain from Dalux support at <support@dalux.com>).
31
- 2. An **API key** — managed via _Settings › Integrations › API Identities_ inside the Dalux Build UI.
32
-
33
- ```js
34
- const { createClient } = require('dalux-build-api');
35
-
36
- const dalux = createClient({
37
- baseUrl: 'https://<your-company>.dalux.com/api',
38
- apiKey: 'YOUR_API_KEY',
39
- });
40
- ```
41
-
42
- The returned object exposes one namespace per API group (see [API Reference](#api-reference) below).
43
-
44
- ### Examples
45
-
46
- **List all projects**
47
- ```js
48
- const projects = await dalux.projects.listProjects();
49
- console.log(projects);
50
- ```
51
-
52
- **Get a specific project**
53
- ```js
54
- const project = await dalux.projects.getProject('my-project-id');
55
- console.log(project);
56
- ```
57
-
58
- **List tasks on a project**
59
- ```js
60
- const tasks = await dalux.tasks.getProjectTasks('my-project-id', {
61
- updatedAfter: '2024-01-01',
62
- });
63
- console.log(tasks);
64
- ```
65
-
66
- **Tasks: OData `typeId` shorthand and fetch all pages**
67
-
68
- `getProjectTasks` forwards OData query options (for example `$filter`). You can also pass `typeId`; it is expanded to `$filter=data/type/typeId eq '<typeId>'` unless you already set `$filter`.
69
-
70
- ```js
71
- const byType = await dalux.tasks.getProjectTasks('my-project-id', { typeId: 'some-type-guid' });
72
-
73
- // All pages merged (bookmark pagination; matches Python client behaviour)
74
- const allTasks = await dalux.tasks.getAllProjectTasks('my-project-id', { typeId: 'some-type-guid' }, false);
75
- ```
76
-
77
- **Files: browse (6.1), fetch all pages, download**
78
-
79
- `listFiles` and `getAllFiles` call **GET `/6.1/projects/{projectId}/file_areas/{fileAreaId}/files`** (Dalux `listFiles`). Supported query parameters include `folderId`, `updatedAfter`, and `includeProperties` (see the official spec). Single-file metadata still uses **GET `/5.0/.../files/{fileId}`** (`getFile`).
80
-
81
- ```js
82
- const allFiles = await dalux.files.getAllFiles('my-project-id', 'my-file-area-id', { folderId: 'folder-guid' });
83
-
84
- const file = await dalux.files.getFile('my-project-id', 'my-file-area-id', 'file-guid', {
85
- download: true,
86
- savePath: './downloads',
87
- });
88
-
89
- const saved = await dalux.files.downloadFileFromLink(downloadUrl, 'model.ifc', './downloads');
90
-
91
- await dalux.files.bulkDownloadFolder('my-project-id', 'my-file-area-id', 'folder-guid', './out', {
92
- filenameExtensions: ['.ifc'],
93
- verbose: true,
94
- });
95
- ```
96
-
97
- **Upload a file (chunked)**
98
- ```js
99
- const fs = require('fs');
100
-
101
- // 1. Create an upload slot
102
- const { uploadGuid } = await dalux.fileUpload.createUpload(
103
- 'my-project-id',
104
- 'my-file-area-id',
105
- { fileName: 'drawing.pdf', mimeType: 'application/pdf' },
106
- );
107
-
108
- // 2. Upload the file in one chunk
109
- const content = fs.readFileSync('./drawing.pdf');
110
- await dalux.fileUpload.uploadFilePart('my-project-id', 'my-file-area-id', uploadGuid, content);
111
-
112
- // 3. Finalize the upload
113
- const result = await dalux.fileUpload.finishUpload(
114
- 'my-project-id',
115
- 'my-file-area-id',
116
- uploadGuid,
117
- { folderId: 'target-folder-id' },
118
- );
119
- console.log('New file ID:', result.fileId);
120
- ```
121
-
122
- ## Authentication
123
-
124
- Every request automatically includes the `X-API-KEY` header with the API key supplied to `createClient`. No additional configuration is required.
125
-
126
- ## Error Handling
127
-
128
- All methods return Promises. Network or HTTP errors (4xx / 5xx) are thrown as Axios errors, so wrap calls with `try/catch` or `.catch()`:
129
-
130
- ```js
131
- try {
132
- const project = await dalux.projects.getProject('unknown-id');
133
- } catch (err) {
134
- console.error(err.response?.status, err.response?.data);
135
- }
136
- ```
137
-
138
- ## API Reference
139
-
140
- All API namespaces are accessible on the object returned by `createClient`:
141
-
142
- | Namespace | Class | Description |
143
- |---|---|---|
144
- | `projects` | `ProjectsApi` | List, get, create and update projects; manage project metadata |
145
- | `companies` | `CompaniesApi` | Project companies (CRUD) |
146
- | `companyCatalog` | `CompanyCatalogApi` | Company catalog (CRUD + metadata) |
147
- | `tasks` | `TasksApi` | Tasks, approvals, safety issues, observations & good practices |
148
- | `fileAreas` | `FileAreasApi` | File areas on a project |
149
- | `files` | `FilesApi` | Files within a file area |
150
- | `folders` | `FoldersApi` | Folders within a file area |
151
- | `fileUpload` | `FileUploadApi` | Chunked file upload (create slot → upload parts → finalize) |
152
- | `fileRevisions` | `FileRevisionsApi` | Download file revision content |
153
- | `forms` | `FormsApi` | Forms and form attachments |
154
- | `users` | `UsersApi` | Company and project users |
155
- | `projectTemplates` | `ProjectTemplatesApi` | Available project templates |
156
- | `inspectionPlans` | `InspectionPlansApi` | Inspection plans, items, zones and registrations |
157
- | `testPlans` | `TestPlansApi` | Test plans, items, zones and registrations |
158
- | `versionSets` | `VersionSetsApi` | Version sets and version set files |
159
- | `workPackages` | `WorkPackagesApi` | Work packages on a project |
160
-
161
- ### ProjectsApi
162
-
163
- | Method | HTTP | Path |
164
- |---|---|---|
165
- | `listProjects(params?)` | GET | `/5.1/projects` |
166
- | `getProject(projectId)` | GET | `/5.0/projects/{projectId}` |
167
- | `createProject(body)` | POST | `/5.0/projects` |
168
- | `updateProject(projectId, body)` | PATCH | `/5.0/projects/{projectId}` |
169
- | `listMetadataMappingsForProjects()` | GET | `/1.0/projects/metadata/1.0/mappings` |
170
- | `listMetadataValuesForProjects(key)` | GET | `/1.0/projects/metadata/1.0/mappings/{key}/values` |
171
- | `listProjectMetadata(projectId)` | GET | `/1.0/projects/{projectId}/metadata` |
172
- | `listProjectMetadataMappings(projectId)` | GET | `/1.0/projects/{projectId}/metadata/1.0/mappings` |
173
- | `listProjectMetadataValues(projectId, key)` | GET | `/1.0/projects/{projectId}/metadata/1.0/mappings/{key}/values` |
174
-
175
- ### CompaniesApi
176
-
177
- | Method | HTTP | Path |
178
- |---|---|---|
179
- | `listProjectCompanies(projectId, params?)` | GET | `/3.1/projects/{projectId}/companies` |
180
- | `getProjectCompany(projectId, companyId)` | GET | `/3.0/projects/{projectId}/companies/{companyId}` |
181
- | `createProjectCompany(projectId, body)` | POST | `/3.1/projects/{projectId}/companies` |
182
- | `updateProjectCompany(projectId, companyId, body)` | PATCH | `/3.0/projects/{projectId}/companies/{companyId}` |
183
-
184
- ### CompanyCatalogApi
185
-
186
- | Method | HTTP | Path |
187
- |---|---|---|
188
- | `getCompanies(params?)` | GET | `/2.2/companyCatalog` |
189
- | `getCompany(catalogCompanyId)` | GET | `/1.2/companyCatalog/{catalogCompanyId}` |
190
- | `createCompany(body)` | POST | `/2.2/companyCatalog` |
191
- | `updateCompany(catalogCompanyId, body)` | PATCH | `/2.1/companyCatalog/{catalogCompanyId}` |
192
- | `listCompanyMetadata(catalogCompanyId)` | GET | `/1.0/companyCatalog/{catalogCompanyId}/metadata` |
193
- | `listCompanyMetadataMappings(catalogCompanyId)` | GET | `/1.0/companyCatalog/{catalogCompanyId}/metadata/1.0/mappings` |
194
- | `listCompanyMetadataValues(catalogCompanyId, key)` | GET | `/1.0/companyCatalog/{catalogCompanyId}/metadata/1.0/mappings/{key}/values` |
195
- | `listMetadataMappingsForCompanies()` | GET | `/1.0/companyCatalog/metadata/1.0/mappings` |
196
- | `listMetadataValuesForCompanies(key)` | GET | `/1.0/companyCatalog/metadata/1.0/mappings/{key}/values` |
197
-
198
- ### TasksApi
199
-
200
- | Method | HTTP | Path |
201
- |---|---|---|
202
- | `getProjectTasks(projectId, params?)` | GET | `/5.2/projects/{projectId}/tasks` |
203
- | `getAllProjectTasks(projectId, params?, verbose?)` | GET (paginated) | `/5.2/projects/{projectId}/tasks` — collects all `items` via `nextPage` / `bookmark`; respects `metadata.totalRemainingItems` or `metadata.totalItems` (Python parity) |
204
- | `getTask(projectId, taskId)` | GET | `/3.3/projects/{projectId}/tasks/{taskId}` |
205
- | `getProjectTaskChanges(projectId, params?)` | GET | `/2.2/projects/{projectId}/tasks/changes` |
206
- | `getProjectTaskAttachments(projectId, params?)` | GET | `/1.1/projects/{projectId}/tasks/attachments` |
207
-
208
- Query params: pass OData options on `getProjectTasks` / `getAllProjectTasks` (for example `$filter`). Shorthand: `typeId` is translated to `$filter=data/type/typeId eq '…'` when `$filter` is not set. `TasksApi.normalizeTaskParams` applies the same rules if you build requests manually.
209
-
210
- ### FileAreasApi
211
-
212
- | Method | HTTP | Path |
213
- |---|---|---|
214
- | `getFileAreas(projectId, params?)` | GET | `/5.1/projects/{projectId}/file_areas` |
215
- | `getFileArea(projectId, fileAreaId)` | GET | `/1.0/projects/{projectId}/file_areas/{fileAreaId}` |
216
-
217
- ### FilesApi
218
-
219
- Browse and paginated helpers use **route version 6.1** for the file collection. `getFile` (one file by id) uses **5.0**, as in the [Dalux Build API](https://app.swaggerhub.com/apis-docs/Dalux/DaluxBuild-api/4.14).
220
-
221
- | Method | HTTP | Path |
222
- |---|---|---|
223
- | `listFiles(projectId, fileAreaId, params?)` | GET | `/6.1/projects/{projectId}/file_areas/{fileAreaId}/files` |
224
- | `getAllFiles(projectId, fileAreaId, params?, verbose?)` | GET (paginated) | Same — all file `items` via bookmark / `metadata.totalRemainingItems` |
225
- | `getAllFilesInFolder(projectId, fileAreaId, folderId, params?, verbose?)` | — | Uses `getAllFiles` then filters by `data.folderId` |
226
- | `getFile(projectId, fileAreaId, fileId, options?)` | GET | `/5.0/.../files/{fileId}` — optional `{ download: true, savePath }` streams to disk (adds `downloadedFilePath`) |
227
- | `downloadFileFromLink(downloadLink, fileName, savePath?)` | GET | Direct download URL with `X-API-KEY` |
228
- | `bulkDownloadFolder(projectId, fileAreaId, folderId, savePath?, opts?)` | — | Optional `filenameKeywords`, `filenameKeywordsMatch` (`any` / `all`), `filenameExtensions`, `params`, `verbose` |
229
- | `bulkDownloadByIds(projectId, fileAreaId, fileIds, savePath?, options?)` | GET + download | Per-id `getFile` then stream from `downloadLink` |
230
- | `getFilePropertiesMapping(projectId, fileAreaId, fileId)` | GET | `/1.0/.../files/{fileId}/properties/1.0/mappings` |
231
- | `getFilePropertyMappingValues(projectId, fileAreaId, filePropertyId)` | GET | `/1.0/.../files/properties/1.0/mappings/{filePropertyId}/values` |
232
-
233
- ### FoldersApi
234
-
235
- | Method | HTTP | Path |
236
- |---|---|---|
237
- | `listFolders(projectId, fileAreaId, params?)` | GET | `/5.1/projects/{projectId}/file_areas/{fileAreaId}/folders` |
238
- | `getFolder(projectId, fileAreaId, folderId)` | GET | `/5.0/projects/{projectId}/file_areas/{fileAreaId}/folders/{folderId}` |
239
- | `getFolderFilesProperties(projectId, fileAreaId, folderId)` | GET | `/1.0/.../folders/{folderId}/files/properties/1.0/mappings` |
240
-
241
- ### FileUploadApi
242
-
243
- | Method | HTTP | Path |
244
- |---|---|---|
245
- | `createUpload(projectId, fileAreaId, body)` | POST | `/1.0/projects/{projectId}/file_areas/{fileAreaId}/upload` |
246
- | `uploadFilePart(projectId, fileAreaId, uploadGuid, chunk)` | POST | `/1.0/.../upload/{uploadGuid}` |
247
- | `finishUpload(projectId, fileAreaId, uploadGuid, body)` | POST | `/2.0/.../upload/{uploadGuid}/finalize` |
248
-
249
- ### FileRevisionsApi
250
-
251
- | Method | HTTP | Path |
252
- |---|---|---|
253
- | `getFileRevisionContent(projectId, fileAreaId, fileId, fileRevisionId)` | GET | `/2.0/.../files/{fileId}/revisions/{fileRevisionId}/content` |
254
-
255
- ### FormsApi
256
-
257
- | Method | HTTP | Path |
258
- |---|---|---|
259
- | `getProjectForms(projectId, params?)` | GET | `/2.1/projects/{projectId}/forms` |
260
- | `getForm(projectId, formId)` | GET | `/1.2/projects/{projectId}/forms/{formId}` |
261
- | `getProjectFormAttachments(projectId, params?)` | GET | `/2.1/projects/{projectId}/forms/attachments` |
262
-
263
- ### UsersApi
264
-
265
- | Method | HTTP | Path |
266
- |---|---|---|
267
- | `getUser(userId)` | GET | `/1.1/users/{userId}` |
268
- | `listProjectUsers(projectId, params?)` | GET | `/1.2/projects/{projectId}/users` |
269
- | `getProjectUser(projectId, userId)` | GET | `/1.1/projects/{projectId}/users/{userId}` |
270
-
271
- ### ProjectTemplatesApi
272
-
273
- | Method | HTTP | Path |
274
- |---|---|---|
275
- | `listProjectTemplates(params?)` | GET | `/1.1/projectTemplates` |
276
-
277
- ### InspectionPlansApi
278
-
279
- | Method | HTTP | Path |
280
- |---|---|---|
281
- | `listInspectionPlans(projectId, params?)` | GET | `/1.2/projects/{projectId}/inspectionPlans` |
282
- | `listInspectionPlanItems(projectId, params?)` | GET | `/1.1/projects/{projectId}/inspectionPlanItems` |
283
- | `listInspectionPlanItemZones(projectId, params?)` | GET | `/1.1/projects/{projectId}/inspectionPlanItemZones` |
284
- | `listInspectionPlanRegistrations(projectId, params?)` | GET | `/2.1/projects/{projectId}/inspectionPlanRegistrations` |
285
-
286
- ### TestPlansApi
287
-
288
- | Method | HTTP | Path |
289
- |---|---|---|
290
- | `listTestPlans(projectId, params?)` | GET | `/1.2/projects/{projectId}/testPlans` |
291
- | `listTestPlanItems(projectId, params?)` | GET | `/1.1/projects/{projectId}/testPlanItems` |
292
- | `listTestPlanItemZones(projectId, params?)` | GET | `/1.1/projects/{projectId}/testPlanItemZones` |
293
- | `listTestPlanRegistrations(projectId, params?)` | GET | `/1.1/projects/{projectId}/testPlanRegistrations` |
294
-
295
- ### VersionSetsApi
296
-
297
- | Method | HTTP | Path |
298
- |---|---|---|
299
- | `getVersionSets(projectId, params?)` | GET | `/2.1/projects/{projectId}/version_sets` |
300
- | `getVersionSet(projectId, versionSetId)` | GET | `/2.0/projects/{projectId}/version_sets/{versionSetId}` |
301
- | `listFileAreaVersionSets(projectId, fileAreaId, params?)` | GET | `/2.1/projects/{projectId}/file_areas/{fileAreaId}/version_sets` |
302
- | `listVersionSetFiles(projectId, versionSetId, params?)` | GET | `/3.0/projects/{projectId}/version_sets/{versionSetId}/files` |
303
-
304
- ### WorkPackagesApi
305
-
306
- | Method | HTTP | Path |
307
- |---|---|---|
308
- | `listWorkPackages(projectId, params?)` | GET | `/1.0/projects/{projectId}/workpackages` |
309
-
310
- ## Advanced Usage
311
-
312
- ### Using individual API classes
313
-
314
- You can also instantiate API classes directly with a shared `ApiClient`:
315
-
316
- ```js
317
- const { Configuration, ApiClient, ProjectsApi, TasksApi } = require('dalux-build-api');
318
-
319
- const config = new Configuration({
320
- baseUrl: 'https://<your-company>.dalux.com/api',
321
- apiKey: 'YOUR_API_KEY',
322
- });
323
- const apiClient = new ApiClient(config);
324
-
325
- const projects = new ProjectsApi(apiClient);
326
- const tasks = new TasksApi(apiClient);
327
- ```
328
-
329
- ## Development
330
-
331
- ```bash
332
- # Install dependencies
333
- npm install
334
-
335
- # Run tests with coverage
336
- npm test
337
- ```
338
-
339
- ## Maintainer: npm releases
340
-
341
- ### Automatic (push to `main`)
342
-
343
- 1. Merge to `main` (or push directly). **CI** must pass.
344
- 2. After **both** the Node and Python test jobs succeed, **CI** calls **Publish npm Package** via `workflow_call` (same run as CI, so it does not depend on `workflow_run`).
345
- 3. The publish job only runs when that push changes `package.json`, `package-lock.json`, `src/`, or `test/`.
346
- 4. **Version bump** uses the same rules as the Python publisher ([commit message tokens](python/README.md#maintainer-pypi-releases)), but the **current** semver is **`max(python/pyproject.toml, package.json)`** so npm catches up when the Python package is ahead.
347
- 5. It runs tests again, publishes to npm, then pushes `chore: release vX.Y.Z [skip npm]`, tag `vX.Y.Z`, and a **GitHub Release** (unless the tag already exists). **`[skip npm]`** skips a second publish pass and skips **CI** on that sync commit.
348
-
349
- ### Manual
350
-
351
- - **Actions → Publish npm Package → Run workflow** for **patch / minor / major** (same test → publish → sync commit → tag → **GitHub Release**). The entry workflow is [npm-publish.yml](.github/workflows/npm-publish.yml); it delegates to [npm-publish-reusable.yml](.github/workflows/npm-publish-reusable.yml) (GitHub requires `workflow_call` in its own file).
352
- - **GitHub Release (published)** publishes the version already in `package.json` at that tag (no version bump in the workflow).
353
-
354
- Create a GitHub **environment** named `npm` with secret **`NPM_TOKEN`**. If pushes or releases from `GITHUB_TOKEN` are blocked, set **`RELEASE_PAT`** as described in [python/README.md](python/README.md#maintainer-pypi-releases).
355
-
356
- ### First publish and `E404` on `npm publish`
357
-
358
- If CI fails with **`404 Not Found - PUT …/dalux-build-api`** and **`is not in this registry`**, the name usually does not exist on npm yet **or** your token is not allowed to **create** it.
359
-
360
- - **Classic [Automation](https://docs.npmjs.com/about-access-tokens#automation-tokens)** tokens only publish packages your account **already** maintains. They cannot create a **new** package name. Fix: run **`npm publish`** once locally (or use a **Publish** classic token / granular token with write access) while logged in as the owner, then switch CI back to an automation token.
361
- - Confirm the package is not taken by someone else: [https://www.npmjs.com/package/dalux-build-api](https://www.npmjs.com/package/dalux-build-api).
362
-
363
- ## License
364
-
365
- MIT
1
+ # Dalux Build API
2
+
3
+ API clients for the [Dalux Build REST API](https://app.swaggerhub.com/apis-docs/Dalux/DaluxBuild-api/4.14), available in two languages:
4
+
5
+ | Language | Location | Documentation |
6
+ |---|---|---|
7
+ | Node.js | [`/`](.) | See below |
8
+ | Python | [`/python`](python/) | [python/README.md](python/README.md) |
9
+
10
+ ---
11
+
12
+ # Node.js Client
13
+
14
+ A lightweight Node.js client for the Dalux Build REST API.
15
+
16
+ ## Requirements
17
+
18
+ - Node.js 14 or later
19
+
20
+ ## Installation
21
+
22
+ ```bash
23
+ npm install @bruadam/dalux-build-api
24
+ ```
25
+
26
+ ## Getting Started
27
+
28
+ To access the API you need:
29
+
30
+ 1. A company-specific **base URL** (obtain from Dalux support at <support@dalux.com>).
31
+ 2. An **API key** — managed via _Settings › Integrations › API Identities_ inside the Dalux Build UI.
32
+
33
+ ```js
34
+ const { createClient } = require('@bruadam/dalux-build-api');
35
+
36
+ const dalux = createClient({
37
+ baseUrl: 'https://<your-company>.dalux.com/api',
38
+ apiKey: 'YOUR_API_KEY',
39
+ });
40
+ ```
41
+
42
+ The returned object exposes one namespace per API group (see [API Reference](#api-reference) below).
43
+
44
+ ### Examples
45
+
46
+ **List all projects**
47
+ ```js
48
+ const projects = await dalux.projects.listProjects();
49
+ console.log(projects);
50
+ ```
51
+
52
+ **Get a specific project**
53
+ ```js
54
+ const project = await dalux.projects.getProject('my-project-id');
55
+ console.log(project);
56
+ ```
57
+
58
+ **List tasks on a project**
59
+ ```js
60
+ const tasks = await dalux.tasks.getProjectTasks('my-project-id', {
61
+ updatedAfter: '2024-01-01',
62
+ });
63
+ console.log(tasks);
64
+ ```
65
+
66
+ **Tasks: OData `typeId` shorthand and fetch all pages**
67
+
68
+ `getProjectTasks` forwards OData query options (for example `$filter`). You can also pass `typeId`; it is expanded to `$filter=data/type/typeId eq '<typeId>'` unless you already set `$filter`.
69
+
70
+ ```js
71
+ const byType = await dalux.tasks.getProjectTasks('my-project-id', { typeId: 'some-type-guid' });
72
+
73
+ // All pages merged (bookmark pagination; matches Python client behaviour)
74
+ const allTasks = await dalux.tasks.getAllProjectTasks('my-project-id', { typeId: 'some-type-guid' }, false);
75
+ ```
76
+
77
+ **Files: browse (6.1), fetch all pages, download**
78
+
79
+ `listFiles` and `getAllFiles` call **GET `/6.1/projects/{projectId}/file_areas/{fileAreaId}/files`** (Dalux `listFiles`). Supported query parameters include `folderId`, `updatedAfter`, and `includeProperties` (see the official spec). Single-file metadata still uses **GET `/5.0/.../files/{fileId}`** (`getFile`).
80
+
81
+ ```js
82
+ const allFiles = await dalux.files.getAllFiles('my-project-id', 'my-file-area-id', { folderId: 'folder-guid' });
83
+
84
+ const file = await dalux.files.getFile('my-project-id', 'my-file-area-id', 'file-guid', {
85
+ download: true,
86
+ savePath: './downloads',
87
+ });
88
+
89
+ const saved = await dalux.files.downloadFileFromLink(downloadUrl, 'model.ifc', './downloads');
90
+
91
+ await dalux.files.bulkDownloadFolder('my-project-id', 'my-file-area-id', 'folder-guid', './out', {
92
+ filenameExtensions: ['.ifc'],
93
+ verbose: true,
94
+ });
95
+ ```
96
+
97
+ **Upload a file (chunked)**
98
+ ```js
99
+ const fs = require('fs');
100
+
101
+ // 1. Create an upload slot
102
+ const { uploadGuid } = await dalux.fileUpload.createUpload(
103
+ 'my-project-id',
104
+ 'my-file-area-id',
105
+ { fileName: 'drawing.pdf', mimeType: 'application/pdf' },
106
+ );
107
+
108
+ // 2. Upload the file in one chunk
109
+ const content = fs.readFileSync('./drawing.pdf');
110
+ await dalux.fileUpload.uploadFilePart('my-project-id', 'my-file-area-id', uploadGuid, content);
111
+
112
+ // 3. Finalize the upload
113
+ const result = await dalux.fileUpload.finishUpload(
114
+ 'my-project-id',
115
+ 'my-file-area-id',
116
+ uploadGuid,
117
+ { folderId: 'target-folder-id' },
118
+ );
119
+ console.log('New file ID:', result.fileId);
120
+ ```
121
+
122
+ ## Authentication
123
+
124
+ Every request automatically includes the `X-API-KEY` header with the API key supplied to `createClient`. No additional configuration is required.
125
+
126
+ ## Error Handling
127
+
128
+ All methods return Promises. Network or HTTP errors (4xx / 5xx) are thrown as Axios errors, so wrap calls with `try/catch` or `.catch()`:
129
+
130
+ ```js
131
+ try {
132
+ const project = await dalux.projects.getProject('unknown-id');
133
+ } catch (err) {
134
+ console.error(err.response?.status, err.response?.data);
135
+ }
136
+ ```
137
+
138
+ ## API Reference
139
+
140
+ All API namespaces are accessible on the object returned by `createClient`:
141
+
142
+ | Namespace | Class | Description |
143
+ |---|---|---|
144
+ | `projects` | `ProjectsApi` | List, get, create and update projects; manage project metadata |
145
+ | `companies` | `CompaniesApi` | Project companies (CRUD) |
146
+ | `companyCatalog` | `CompanyCatalogApi` | Company catalog (CRUD + metadata) |
147
+ | `tasks` | `TasksApi` | Tasks, approvals, safety issues, observations & good practices |
148
+ | `fileAreas` | `FileAreasApi` | File areas on a project |
149
+ | `files` | `FilesApi` | Files within a file area |
150
+ | `folders` | `FoldersApi` | Folders within a file area |
151
+ | `fileUpload` | `FileUploadApi` | Chunked file upload (create slot → upload parts → finalize) |
152
+ | `fileRevisions` | `FileRevisionsApi` | Download file revision content |
153
+ | `forms` | `FormsApi` | Forms and form attachments |
154
+ | `users` | `UsersApi` | Company and project users |
155
+ | `projectTemplates` | `ProjectTemplatesApi` | Available project templates |
156
+ | `inspectionPlans` | `InspectionPlansApi` | Inspection plans, items, zones and registrations |
157
+ | `testPlans` | `TestPlansApi` | Test plans, items, zones and registrations |
158
+ | `versionSets` | `VersionSetsApi` | Version sets and version set files |
159
+ | `workPackages` | `WorkPackagesApi` | Work packages on a project |
160
+
161
+ ### ProjectsApi
162
+
163
+ | Method | HTTP | Path |
164
+ |---|---|---|
165
+ | `listProjects(params?)` | GET | `/5.1/projects` |
166
+ | `getProject(projectId)` | GET | `/5.0/projects/{projectId}` |
167
+ | `createProject(body)` | POST | `/5.0/projects` |
168
+ | `updateProject(projectId, body)` | PATCH | `/5.0/projects/{projectId}` |
169
+ | `listMetadataMappingsForProjects()` | GET | `/1.0/projects/metadata/1.0/mappings` |
170
+ | `listMetadataValuesForProjects(key)` | GET | `/1.0/projects/metadata/1.0/mappings/{key}/values` |
171
+ | `listProjectMetadata(projectId)` | GET | `/1.0/projects/{projectId}/metadata` |
172
+ | `listProjectMetadataMappings(projectId)` | GET | `/1.0/projects/{projectId}/metadata/1.0/mappings` |
173
+ | `listProjectMetadataValues(projectId, key)` | GET | `/1.0/projects/{projectId}/metadata/1.0/mappings/{key}/values` |
174
+
175
+ ### CompaniesApi
176
+
177
+ | Method | HTTP | Path |
178
+ |---|---|---|
179
+ | `listProjectCompanies(projectId, params?)` | GET | `/3.1/projects/{projectId}/companies` |
180
+ | `getProjectCompany(projectId, companyId)` | GET | `/3.0/projects/{projectId}/companies/{companyId}` |
181
+ | `createProjectCompany(projectId, body)` | POST | `/3.1/projects/{projectId}/companies` |
182
+ | `updateProjectCompany(projectId, companyId, body)` | PATCH | `/3.0/projects/{projectId}/companies/{companyId}` |
183
+
184
+ ### CompanyCatalogApi
185
+
186
+ | Method | HTTP | Path |
187
+ |---|---|---|
188
+ | `getCompanies(params?)` | GET | `/2.2/companyCatalog` |
189
+ | `getCompany(catalogCompanyId)` | GET | `/1.2/companyCatalog/{catalogCompanyId}` |
190
+ | `createCompany(body)` | POST | `/2.2/companyCatalog` |
191
+ | `updateCompany(catalogCompanyId, body)` | PATCH | `/2.1/companyCatalog/{catalogCompanyId}` |
192
+ | `listCompanyMetadata(catalogCompanyId)` | GET | `/1.0/companyCatalog/{catalogCompanyId}/metadata` |
193
+ | `listCompanyMetadataMappings(catalogCompanyId)` | GET | `/1.0/companyCatalog/{catalogCompanyId}/metadata/1.0/mappings` |
194
+ | `listCompanyMetadataValues(catalogCompanyId, key)` | GET | `/1.0/companyCatalog/{catalogCompanyId}/metadata/1.0/mappings/{key}/values` |
195
+ | `listMetadataMappingsForCompanies()` | GET | `/1.0/companyCatalog/metadata/1.0/mappings` |
196
+ | `listMetadataValuesForCompanies(key)` | GET | `/1.0/companyCatalog/metadata/1.0/mappings/{key}/values` |
197
+
198
+ ### TasksApi
199
+
200
+ | Method | HTTP | Path |
201
+ |---|---|---|
202
+ | `getProjectTasks(projectId, params?)` | GET | `/5.2/projects/{projectId}/tasks` |
203
+ | `getAllProjectTasks(projectId, params?, verbose?)` | GET (paginated) | `/5.2/projects/{projectId}/tasks` — collects all `items` via `nextPage` / `bookmark`; respects `metadata.totalRemainingItems` or `metadata.totalItems` (Python parity) |
204
+ | `getTask(projectId, taskId)` | GET | `/3.3/projects/{projectId}/tasks/{taskId}` |
205
+ | `getProjectTaskChanges(projectId, params?)` | GET | `/2.2/projects/{projectId}/tasks/changes` |
206
+ | `getProjectTaskAttachments(projectId, params?)` | GET | `/1.1/projects/{projectId}/tasks/attachments` |
207
+
208
+ Query params: pass OData options on `getProjectTasks` / `getAllProjectTasks` (for example `$filter`). Shorthand: `typeId` is translated to `$filter=data/type/typeId eq '…'` when `$filter` is not set. `TasksApi.normalizeTaskParams` applies the same rules if you build requests manually.
209
+
210
+ ### FileAreasApi
211
+
212
+ | Method | HTTP | Path |
213
+ |---|---|---|
214
+ | `getFileAreas(projectId, params?)` | GET | `/5.1/projects/{projectId}/file_areas` |
215
+ | `getFileArea(projectId, fileAreaId)` | GET | `/1.0/projects/{projectId}/file_areas/{fileAreaId}` |
216
+
217
+ ### FilesApi
218
+
219
+ Browse and paginated helpers use **route version 6.1** for the file collection. `getFile` (one file by id) uses **5.0**, as in the [Dalux Build API](https://app.swaggerhub.com/apis-docs/Dalux/DaluxBuild-api/4.14).
220
+
221
+ | Method | HTTP | Path |
222
+ |---|---|---|
223
+ | `listFiles(projectId, fileAreaId, params?)` | GET | `/6.1/projects/{projectId}/file_areas/{fileAreaId}/files` |
224
+ | `getAllFiles(projectId, fileAreaId, params?, verbose?)` | GET (paginated) | Same — all file `items` via bookmark / `metadata.totalRemainingItems` |
225
+ | `getAllFilesInFolder(projectId, fileAreaId, folderId, params?, verbose?)` | — | Uses `getAllFiles` then filters by `data.folderId` |
226
+ | `getFile(projectId, fileAreaId, fileId, options?)` | GET | `/5.0/.../files/{fileId}` — optional `{ download: true, savePath }` streams to disk (adds `downloadedFilePath`) |
227
+ | `downloadFileFromLink(downloadLink, fileName, savePath?)` | GET | Direct download URL with `X-API-KEY` |
228
+ | `bulkDownloadFolder(projectId, fileAreaId, folderId, savePath?, opts?)` | — | Optional `filenameKeywords`, `filenameKeywordsMatch` (`any` / `all`), `filenameExtensions`, `params`, `verbose` |
229
+ | `bulkDownloadByIds(projectId, fileAreaId, fileIds, savePath?, options?)` | GET + download | Per-id `getFile` then stream from `downloadLink` |
230
+ | `getFilePropertiesMapping(projectId, fileAreaId, fileId)` | GET | `/1.0/.../files/{fileId}/properties/1.0/mappings` |
231
+ | `getFilePropertyMappingValues(projectId, fileAreaId, filePropertyId)` | GET | `/1.0/.../files/properties/1.0/mappings/{filePropertyId}/values` |
232
+
233
+ ### FoldersApi
234
+
235
+ | Method | HTTP | Path |
236
+ |---|---|---|
237
+ | `listFolders(projectId, fileAreaId, params?)` | GET | `/5.1/projects/{projectId}/file_areas/{fileAreaId}/folders` |
238
+ | `getFolder(projectId, fileAreaId, folderId)` | GET | `/5.0/projects/{projectId}/file_areas/{fileAreaId}/folders/{folderId}` |
239
+ | `getFolderFilesProperties(projectId, fileAreaId, folderId)` | GET | `/1.0/.../folders/{folderId}/files/properties/1.0/mappings` |
240
+
241
+ ### FileUploadApi
242
+
243
+ | Method | HTTP | Path |
244
+ |---|---|---|
245
+ | `createUpload(projectId, fileAreaId, body)` | POST | `/1.0/projects/{projectId}/file_areas/{fileAreaId}/upload` |
246
+ | `uploadFilePart(projectId, fileAreaId, uploadGuid, chunk)` | POST | `/1.0/.../upload/{uploadGuid}` |
247
+ | `finishUpload(projectId, fileAreaId, uploadGuid, body)` | POST | `/2.0/.../upload/{uploadGuid}/finalize` |
248
+
249
+ ### FileRevisionsApi
250
+
251
+ | Method | HTTP | Path |
252
+ |---|---|---|
253
+ | `getFileRevisionContent(projectId, fileAreaId, fileId, fileRevisionId)` | GET | `/2.0/.../files/{fileId}/revisions/{fileRevisionId}/content` |
254
+
255
+ ### FormsApi
256
+
257
+ | Method | HTTP | Path |
258
+ |---|---|---|
259
+ | `getProjectForms(projectId, params?)` | GET | `/2.1/projects/{projectId}/forms` |
260
+ | `getForm(projectId, formId)` | GET | `/1.2/projects/{projectId}/forms/{formId}` |
261
+ | `getProjectFormAttachments(projectId, params?)` | GET | `/2.1/projects/{projectId}/forms/attachments` |
262
+
263
+ ### UsersApi
264
+
265
+ | Method | HTTP | Path |
266
+ |---|---|---|
267
+ | `getUser(userId)` | GET | `/1.1/users/{userId}` |
268
+ | `listProjectUsers(projectId, params?)` | GET | `/1.2/projects/{projectId}/users` |
269
+ | `getProjectUser(projectId, userId)` | GET | `/1.1/projects/{projectId}/users/{userId}` |
270
+
271
+ ### ProjectTemplatesApi
272
+
273
+ | Method | HTTP | Path |
274
+ |---|---|---|
275
+ | `listProjectTemplates(params?)` | GET | `/1.1/projectTemplates` |
276
+
277
+ ### InspectionPlansApi
278
+
279
+ | Method | HTTP | Path |
280
+ |---|---|---|
281
+ | `listInspectionPlans(projectId, params?)` | GET | `/1.2/projects/{projectId}/inspectionPlans` |
282
+ | `listInspectionPlanItems(projectId, params?)` | GET | `/1.1/projects/{projectId}/inspectionPlanItems` |
283
+ | `listInspectionPlanItemZones(projectId, params?)` | GET | `/1.1/projects/{projectId}/inspectionPlanItemZones` |
284
+ | `listInspectionPlanRegistrations(projectId, params?)` | GET | `/2.1/projects/{projectId}/inspectionPlanRegistrations` |
285
+
286
+ ### TestPlansApi
287
+
288
+ | Method | HTTP | Path |
289
+ |---|---|---|
290
+ | `listTestPlans(projectId, params?)` | GET | `/1.2/projects/{projectId}/testPlans` |
291
+ | `listTestPlanItems(projectId, params?)` | GET | `/1.1/projects/{projectId}/testPlanItems` |
292
+ | `listTestPlanItemZones(projectId, params?)` | GET | `/1.1/projects/{projectId}/testPlanItemZones` |
293
+ | `listTestPlanRegistrations(projectId, params?)` | GET | `/1.1/projects/{projectId}/testPlanRegistrations` |
294
+
295
+ ### VersionSetsApi
296
+
297
+ | Method | HTTP | Path |
298
+ |---|---|---|
299
+ | `getVersionSets(projectId, params?)` | GET | `/2.1/projects/{projectId}/version_sets` |
300
+ | `getVersionSet(projectId, versionSetId)` | GET | `/2.0/projects/{projectId}/version_sets/{versionSetId}` |
301
+ | `listFileAreaVersionSets(projectId, fileAreaId, params?)` | GET | `/2.1/projects/{projectId}/file_areas/{fileAreaId}/version_sets` |
302
+ | `listVersionSetFiles(projectId, versionSetId, params?)` | GET | `/3.0/projects/{projectId}/version_sets/{versionSetId}/files` |
303
+
304
+ ### WorkPackagesApi
305
+
306
+ | Method | HTTP | Path |
307
+ |---|---|---|
308
+ | `listWorkPackages(projectId, params?)` | GET | `/1.0/projects/{projectId}/workpackages` |
309
+
310
+ ## Advanced Usage
311
+
312
+ ### Using individual API classes
313
+
314
+ You can also instantiate API classes directly with a shared `ApiClient`:
315
+
316
+ ```js
317
+ const { Configuration, ApiClient, ProjectsApi, TasksApi } = require('@bruadam/dalux-build-api');
318
+
319
+ const config = new Configuration({
320
+ baseUrl: 'https://<your-company>.dalux.com/api',
321
+ apiKey: 'YOUR_API_KEY',
322
+ });
323
+ const apiClient = new ApiClient(config);
324
+
325
+ const projects = new ProjectsApi(apiClient);
326
+ const tasks = new TasksApi(apiClient);
327
+ ```
328
+
329
+ ## Development
330
+
331
+ ```bash
332
+ # Install dependencies
333
+ npm install
334
+
335
+ # Run tests with coverage
336
+ npm test
337
+ ```
338
+
339
+ ## Maintainer: npm releases
340
+
341
+ ### Automatic (push to `main`)
342
+
343
+ 1. Merge to `main` (or push directly). **CI** must pass.
344
+ 2. After **both** the Node and Python test jobs succeed, **CI** calls **Publish npm Package** via `workflow_call` (same run as CI, so it does not depend on `workflow_run`).
345
+ 3. The publish job only runs when that push changes `package.json`, `package-lock.json`, `src/`, or `test/`.
346
+ 4. **Version bump** uses the same rules as the Python publisher ([commit message tokens](python/README.md#maintainer-pypi-releases)), but the **current** semver is **`max(python/pyproject.toml, package.json)`** so npm catches up when the Python package is ahead.
347
+ 5. It runs tests again, publishes to npm, then pushes `chore: release vX.Y.Z [skip npm]`, tag `vX.Y.Z`, and a **GitHub Release** (unless the tag already exists). **`[skip npm]`** skips a second publish pass and skips **CI** on that sync commit.
348
+
349
+ ### Manual
350
+
351
+ - **Actions → Publish npm Package → Run workflow** for **patch / minor / major** (same test → publish → sync commit → tag → **GitHub Release**). The entry workflow is [npm-publish.yml](.github/workflows/npm-publish.yml); it delegates to [npm-publish-reusable.yml](.github/workflows/npm-publish-reusable.yml) (GitHub requires `workflow_call` in its own file).
352
+ - **GitHub Release (published)** publishes the version already in `package.json` at that tag (no version bump in the workflow).
353
+
354
+ Create a GitHub **environment** named `npm` with secret **`NPM_TOKEN`**. If pushes or releases from `GITHUB_TOKEN` are blocked, set **`RELEASE_PAT`** as described in [python/README.md](python/README.md#maintainer-pypi-releases).
355
+
356
+ ### First publish and `E404` on `npm publish`
357
+
358
+ If CI fails with **`404 Not Found - PUT …/@bruadam/dalux-build-api`** and **`is not in this registry`**, the package does not exist on npm yet **or** your token is not allowed to **create** it.
359
+
360
+ - **Classic [Automation](https://docs.npmjs.com/about-access-tokens#automation-tokens)** tokens only publish packages your account **already** maintains. They cannot create a **new** package name. Fix: use a **granular access token** with write access to the `@bruadam` scope (or all packages), or run **`npm publish --access public`** once locally while logged in as the owner, then switch CI back to an automation token.
361
+ - Confirm the package is not taken by someone else: [https://www.npmjs.com/package/@bruadam/dalux-build-api](https://www.npmjs.com/package/@bruadam/dalux-build-api).
362
+
363
+ ## License
364
+
365
+ MIT