dalux-build-api 2.3.0 → 2.5.0

package/README.md

@@ -202,6 +202,58 @@ const result = await dalux.fileUpload.finishUpload(
 console.log("New file ID:", result.fileId);
 ```
 
+## Browser and plugin hosts (`/web`)
+
+When the API key legitimately lives where the code runs — a desktop app, an extension, a plugin
+host that already proxies Dalux — `dalux-build-api/web` gives you every endpoint group over a
+`fetch` you supply:
+
+```ts
+import { createWebClient } from "dalux-build-api/web";
+
+const dalux = createWebClient({
+  baseUrl: "https://node1.field.dalux.com/service/api",
+  apiKey,
+  fetch: ctx.fetch,                      // the host's own fetch
+  defaultParams: { daluxNode: "node2" }, // base-origin requests only
+});
+
+const sets = await dalux.versionSets.getVersionSets(projectId);
+```
+
+`fetch` is required and never falls back to `globalThis.fetch`. A sandboxed host hands its own
+fetch down because that wrapper is where the outbound-host allow-list, the same-origin relay for
+an API that sends no CORS headers, redirect refusal and credential omission are enforced; silently
+using the global would take all of that off without the caller noticing. `defaultParams` are added
+only to requests on the configured base URL, and never override a parameter the caller or the URL
+already set — a `downloadLink` can carry a signature computed over its query string.
+
+This entry reaches no Axios, no `fs`/`path`/`readline`, no `process.env` — enforced by a test over
+the module graph, not by a build flag. The one omission is `FilesApi`: its bulk-download and
+interactive-selection helpers stream to disk and read stdin. Its pure HTTP reads, including
+`downloadFileBytes`, are on `FilesReadApi` and exposed as `dalux.files`.
+
+### Bringing your own HTTP client
+
+If your host already has a Dalux client — with its own relay, retries, logging or pagination rules
+— implement `DaluxHttpClient` over it and keep all of that while still getting the endpoint
+catalogue and its zod models:
+
+```ts
+import { createWebClientFrom, type DaluxHttpClient } from "dalux-build-api/web";
+
+const http: DaluxHttpClient = {
+  configuration: { baseUrl, apiKey },
+  get: (path, params, config) => host.get(path, params, config?.signal),
+  post: (path, body, params) => host.post(path, body, params),
+  patch: (path, body, params) => host.patch(path, body, params),
+  delete: (path, params) => host.delete(path, params),
+  binary: async (url, config) => ({ bytes: await host.getBinary(url, config?.signal) }),
+};
+
+const dalux = createWebClientFrom(http);
+```
+
 ## Authentication
 
 Every request automatically includes the `X-API-KEY` header with the API key supplied to `createClient`. No additional configuration is required.

package/package.json

@@ -1,22 +1,61 @@
 {
   "name": "dalux-build-api",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "description": "Node.js client for the Dalux Build API",
-  "main": "src/index.js",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
-    ".": "./src/index.js",
-    "./browser": "./src/browser.js",
-    "./next": "./src/next.js"
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./browser": {
+      "import": {
+        "types": "./dist/browser.d.mts",
+        "default": "./dist/browser.mjs"
+      },
+      "require": {
+        "types": "./dist/browser.d.ts",
+        "default": "./dist/browser.js"
+      }
+    },
+    "./next": {
+      "import": {
+        "types": "./dist/next.d.mts",
+        "default": "./dist/next.mjs"
+      },
+      "require": {
+        "types": "./dist/next.d.ts",
+        "default": "./dist/next.js"
+      }
+    },
+    "./web": {
+      "import": {
+        "types": "./dist/web.d.mts",
+        "default": "./dist/web.mjs"
+      },
+      "require": {
+        "types": "./dist/web.d.ts",
+        "default": "./dist/web.js"
+      }
+    }
   },
   "files": [
-    "src",
+    "dist",
     "README.md"
   ],
   "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
     "test": "jest --coverage",
-    "build": "npm pack",
-    "pack:check": "npm pack --dry-run",
-    "release:check": "npm test && npm run pack:check"
+    "pack:check": "npm run build && npm pack --dry-run",
+    "release:check": "npm run typecheck && npm test && npm run pack:check"
   },
   "keywords": [
     "dalux",
@@ -44,10 +83,20 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^22.0.0",
     "axios-mock-adapter": "^2.1.0",
-    "jest": "^30.4.2"
+    "jest": "^30.4.2",
+    "ts-jest": "^29.2.5",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2"
   },
   "jest": {
-    "testEnvironment": "node"
-  }
+    "testEnvironment": "node",
+    "preset": "ts-jest",
+    "testMatch": [
+      "**/test/**/*.test.ts"
+    ]
+  },
+  "module": "dist/index.mjs"
 }

package/src/api/CompaniesApi.js

@@ -1,67 +0,0 @@
-'use strict';
-
-const { convertToModel } = require('../models/convert');
-const { CompaniesListResponseSchema, CompanyResponseSchema } = require('../models/companies');
-
-/**
- * API methods for managing companies on a project.
- */
-class CompaniesApi {
-  /**
-   * @param {import('../apiClient')} apiClient
-   */
-  constructor(apiClient) {
-    this._client = apiClient;
-  }
-
-  /**
-   * Get companies on a project.
-   * GET /3.1/projects/{projectId}/companies
-   * @param {string} projectId
-   * @param {object} [params]
-   * @returns {Promise<object>} CompaniesListResponse ({ items: ProjectCompany[], metadata?, links? })
-   */
-  async listProjectCompanies(projectId, params = {}) {
-    const response = await this._client.get(`/3.1/projects/${projectId}/companies`, params);
-    return convertToModel(response, CompaniesListResponseSchema, 'CompaniesListResponse');
-  }
-
-  /**
-   * Get a specific company on a project.
-   * GET /3.0/projects/{projectId}/companies/{companyId}
-   * @param {string} projectId
-   * @param {string} companyId
-   * @returns {Promise<object>} CompanyResponse ({ data: ProjectCompany, links? })
-   */
-  async getProjectCompany(projectId, companyId) {
-    const response = await this._client.get(`/3.0/projects/${projectId}/companies/${companyId}`);
-    return convertToModel(response, CompanyResponseSchema, 'CompanyResponse');
-  }
-
-  /**
-   * Add a company to a project.
-   * POST /3.1/projects/{projectId}/companies
-   * @param {string} projectId
-   * @param {object} body
-   * @returns {Promise<object>} CompanyResponse
-   */
-  async createProjectCompany(projectId, body) {
-    const response = await this._client.post(`/3.1/projects/${projectId}/companies`, body);
-    return convertToModel(response, CompanyResponseSchema, 'CompanyResponse');
-  }
-
-  /**
-   * Update a company on a project.
-   * PATCH /3.0/projects/{projectId}/companies/{companyId}
-   * @param {string} projectId
-   * @param {string} companyId
-   * @param {object} body
-   * @returns {Promise<object>} CompanyResponse
-   */
-  async updateProjectCompany(projectId, companyId, body) {
-    const response = await this._client.patch(`/3.0/projects/${projectId}/companies/${companyId}`, body);
-    return convertToModel(response, CompanyResponseSchema, 'CompanyResponse');
-  }
-}
-
-module.exports = CompaniesApi;

package/src/api/CompanyCatalogApi.js

@@ -1,129 +0,0 @@
-'use strict';
-
-const { findByField } = require('../utils/search');
-const { convertToModel } = require('../models/convert');
-const { CompaniesListResponseSchema, CompanyResponseSchema } = require('../models/companies');
-
-/**
- * API methods for the company catalog.
- */
-class CompanyCatalogApi {
-  /**
-   * @param {import('../apiClient')} apiClient
-   */
-  constructor(apiClient) {
-    this._client = apiClient;
-  }
-
-  /**
-   * Get companies registered in the company catalog.
-   * GET /2.2/companyCatalog
-   * @param {object} [params]
-   * @returns {Promise<object>} CompaniesListResponse ({ items: ProjectCompany[], metadata?, links? })
-   */
-  async getCompanies(params = {}) {
-    const response = await this._client.get('/2.2/companyCatalog', params);
-    return convertToModel(response, CompaniesListResponseSchema, 'CompaniesListResponse');
-  }
-
-  /**
-   * Get a specific company from the catalog.
-   * GET /1.2/companyCatalog/{catalogCompanyId}
-   * @param {string} catalogCompanyId
-   * @returns {Promise<object>} CompanyResponse ({ data: ProjectCompany, links? })
-   */
-  async getCompany(catalogCompanyId) {
-    const response = await this._client.get(`/1.2/companyCatalog/${catalogCompanyId}`);
-    return convertToModel(response, CompanyResponseSchema, 'CompanyResponse');
-  }
-
-  /**
-   * Add a company to the catalog.
-   * POST /2.2/companyCatalog
-   * @param {object} body
-   * @returns {Promise<object>} CompanyResponse
-   */
-  async createCompany(body) {
-    const response = await this._client.post('/2.2/companyCatalog', body);
-    return convertToModel(response, CompanyResponseSchema, 'CompanyResponse');
-  }
-
-  /**
-   * Update a company in the catalog.
-   * PATCH /2.1/companyCatalog/{catalogCompanyId}
-   * @param {string} catalogCompanyId
-   * @param {object} body
-   * @returns {Promise<object>} CompanyResponse
-   */
-  async updateCompany(catalogCompanyId, body) {
-    const response = await this._client.patch(`/2.1/companyCatalog/${catalogCompanyId}`, body);
-    return convertToModel(response, CompanyResponseSchema, 'CompanyResponse');
-  }
-
-  /**
-   * Get metadata of a specific company from the catalog.
-   * GET /1.0/companyCatalog/{catalogCompanyId}/metadata
-   * @param {string} catalogCompanyId
-   * @returns {Promise<object>}
-   */
-  listCompanyMetadata(catalogCompanyId) {
-    return this._client.get(`/1.0/companyCatalog/${catalogCompanyId}/metadata`);
-  }
-
-  /**
-   * Get all metadata available for a PATCH company-catalog operation.
-   * GET /1.0/companyCatalog/{catalogCompanyId}/metadata/1.0/mappings
-   * @param {string} catalogCompanyId
-   * @returns {Promise<object>}
-   */
-  listCompanyMetadataMappings(catalogCompanyId) {
-    return this._client.get(`/1.0/companyCatalog/${catalogCompanyId}/metadata/1.0/mappings`);
-  }
-
-  /**
-   * Get available values for metadata in a PATCH company-catalog operation.
-   * GET /1.0/companyCatalog/{catalogCompanyId}/metadata/1.0/mappings/{key}/values
-   * @param {string} catalogCompanyId
-   * @param {string} key
-   * @returns {Promise<object>}
-   */
-  listCompanyMetadataValues(catalogCompanyId, key) {
-    return this._client.get(
-      `/1.0/companyCatalog/${catalogCompanyId}/metadata/1.0/mappings/${key}/values`,
-    );
-  }
-
-  /**
-   * Get all metadata available for a POST company-catalog operation.
-   * GET /1.0/companyCatalog/metadata/1.0/mappings
-   * @returns {Promise<object>}
-   */
-  listMetadataMappingsForCompanies() {
-    return this._client.get('/1.0/companyCatalog/metadata/1.0/mappings');
-  }
-
-  /**
-   * Get available values for metadata in a POST company-catalog operation.
-   * GET /1.0/companyCatalog/metadata/1.0/mappings/{key}/values
-   * @param {string} key
-   * @returns {Promise<object>}
-   */
-  listMetadataValuesForCompanies(key) {
-    return this._client.get(`/1.0/companyCatalog/metadata/1.0/mappings/${key}/values`);
-  }
-
-  /**
-   * Get a company ID by its name from the catalog.
-   * @param {string} companyName
-   * @returns {Promise<string|null>} The catalogCompanyId, or null if not found.
-   */
-  async getCompanyByName(companyName) {
-    const response = await this.getCompanies();
-    const items = (response && response.items) || [];
-    const company = findByField(items, 'name', companyName);
-    if (!company) return null;
-    return company.catalogCompanyId || null;
-  }
-}
-
-module.exports = CompanyCatalogApi;

package/src/api/FileAreasApi.js

@@ -1,57 +0,0 @@
-'use strict';
-
-const { findByField } = require('../utils/search');
-const { convertToModel } = require('../models/convert');
-const { FileAreaSchema, FileAreasListResponseSchema } = require('../models/fileAreas');
-
-/**
- * API methods for file areas on a project.
- */
-class FileAreasApi {
-  /**
-   * @param {import('../apiClient')} apiClient
-   */
-  constructor(apiClient) {
-    this._client = apiClient;
-  }
-
-  /**
-   * Retrieve the file areas on the given project.
-   * GET /5.1/projects/{projectId}/file_areas
-   * @param {string} projectId
-   * @param {object} [params]
-   * @returns {Promise<object>} FileAreasListResponse ({ items: FileArea[], metadata?, links? })
-   */
-  async getFileAreas(projectId, params = {}) {
-    const response = await this._client.get(`/5.1/projects/${projectId}/file_areas`, params);
-    return convertToModel(response, FileAreasListResponseSchema, 'FileAreasListResponse');
-  }
-
-  /**
-   * Retrieve a specific file area.
-   * GET /1.0/projects/{projectId}/file_areas/{fileAreaId}
-   * @param {string} projectId
-   * @param {string} fileAreaId
-   * @returns {Promise<object>} FileArea (not wrapped in a data envelope, matches Python)
-   */
-  async getFileArea(projectId, fileAreaId) {
-    const response = await this._client.get(`/1.0/projects/${projectId}/file_areas/${fileAreaId}`);
-    return convertToModel(response, FileAreaSchema, 'FileArea');
-  }
-
-  /**
-   * Get a file area ID by its name for a project.
-   * @param {string} projectId
-   * @param {string} fileAreaName
-   * @returns {Promise<string|null>} The fileAreaId, or null if not found.
-   */
-  async getFileAreaByName(projectId, fileAreaName) {
-    const response = await this.getFileAreas(projectId);
-    const items = (response && response.items) || [];
-    const area = findByField(items, 'fileAreaName', fileAreaName);
-    if (!area) return null;
-    return area.fileAreaId || null;
-  }
-}
-
-module.exports = FileAreasApi;

package/src/api/FileRevisionsApi.js

@@ -1,33 +0,0 @@
-'use strict';
-
-/**
- * API methods for file revision content.
- */
-class FileRevisionsApi {
-  /**
-   * @param {import('../apiClient')} apiClient
-   */
-  constructor(apiClient) {
-    this._client = apiClient;
-  }
-
-  /**
-   * Retrieve content of a specific file revision.
-   * GET /2.0/projects/{projectId}/file_areas/{fileAreaId}/files/{fileId}/revisions/{fileRevisionId}/content
-   * @param {string} projectId
-   * @param {string} fileAreaId
-   * @param {string} fileId
-   * @param {string} fileRevisionId
-   * @returns {Promise<Buffer>} Raw binary content
-   */
-  async getFileRevisionContent(projectId, fileAreaId, fileId, fileRevisionId) {
-    const data = await this._client.get(
-      `/2.0/projects/${projectId}/file_areas/${fileAreaId}/files/${fileId}/revisions/${fileRevisionId}/content`,
-      {},
-      { responseType: 'arraybuffer' },
-    );
-    return Buffer.from(data);
-  }
-}
-
-module.exports = FileRevisionsApi;

package/src/api/FileUploadApi.js

@@ -1,64 +0,0 @@
-'use strict';
-
-/**
- * API methods for chunked file uploads.
- */
-class FileUploadApi {
-  /**
-   * @param {import('../apiClient')} apiClient
-   */
-  constructor(apiClient) {
-    this._client = apiClient;
-  }
-
-  /**
-   * Create a new upload slot and return a GUID pointing to that slot.
-   * POST /1.0/projects/{projectId}/file_areas/{fileAreaId}/upload
-   * @param {string} projectId
-   * @param {string} fileAreaId
-   * @param {object} body
-   * @returns {Promise<object>}
-   */
-  createUpload(projectId, fileAreaId, body) {
-    return this._client.post(
-      `/1.0/projects/${projectId}/file_areas/${fileAreaId}/upload`,
-      body,
-    );
-  }
-
-  /**
-   * Upload a part of a file.
-   * POST /1.0/projects/{projectId}/file_areas/{fileAreaId}/upload/{uploadGuid}
-   * @param {string} projectId
-   * @param {string} fileAreaId
-   * @param {string} uploadGuid
-   * @param {Buffer|Uint8Array} chunk - Binary file chunk
-   * @returns {Promise<object>}
-   */
-  uploadFilePart(projectId, fileAreaId, uploadGuid, chunk) {
-    return this._client.post(
-      `/1.0/projects/${projectId}/file_areas/${fileAreaId}/upload/${uploadGuid}`,
-      chunk,
-      {},
-      { headers: { 'Content-Type': 'application/octet-stream' } },
-    );
-  }
-
-  /**
-   * Finish uploading a file (finalize the upload).
-   * POST /2.0/projects/{projectId}/file_areas/{fileAreaId}/upload/{uploadGuid}/finalize
-   * @param {string} projectId
-   * @param {string} fileAreaId
-   * @param {string} uploadGuid
-   * @param {object} body
-   * @returns {Promise<object>}
-   */
-  finishUpload(projectId, fileAreaId, uploadGuid, body) {
-    return this._client.post(
-      `/2.0/projects/${projectId}/file_areas/${fileAreaId}/upload/${uploadGuid}/finalize`,
-      body,
-    );
-  }
-}
-
-module.exports = FileUploadApi;