bimplus-websdk 1.0.63 → 1.0.65

package/.github/copilot-instructions.md

@@ -0,0 +1,64 @@
+# GitHub Copilot Instructions — Bimplus WebSDK
+
+> **Path convention:** This repository contains multiple packages. Unless stated otherwise, **all paths in this document are relative to the `websdk/` package root** (i.e. `websdk/` in the repository). For example, `src/Api/Api.js` refers to `websdk/src/Api/Api.js` in the repository, and `types/bimplus-websdk.d.ts` refers to `websdk/types/bimplus-websdk.d.ts`.
+
+## Project Overview
+This is the **Bimplus WebSDK** (`bimplus-websdk`), a JavaScript wrapper around the Bimplus REST API developed by Allplan. It is a UMD library built with Webpack + Babel, targeting both browser and Node/CommonJS consumers. The entry point is `websdk/src/Api/Api.js` and the compiled output is `websdk/dist/bimplus-websdk.js`.
+
+## Repository Structure
+All paths below are relative to `websdk/`:
+- `src/Api/` — All API module source files (one class per resource, e.g. `Projects.js`, `Models.js`)
+- `test/api_tests/` — QUnit integration tests (one file per API module, suffixed `Tests.js`)
+- `test/helpers/` — Shared test helpers (`ApiHelper.js`, etc.)
+- `types/bimplus-websdk.d.ts` — TypeScript type declarations for the public API
+- `dist/` — Build output (do not edit manually)
+- `documentation/` — Auto-generated docs (JSDoc via `documentation` package)
+
+## Language & Style
+- **ES2022 modules** (`import`/`export`) throughout `src/` and `test/`
+- **No TypeScript** in source files — only `.js`. The `types/` folder contains handwritten `.d.ts` declarations that must be kept in sync manually when adding new public methods.
+- **Semicolons are required** (enforced by ESLint: `semi: ["warn", "always"]`).
+- Use `const`/`let` — never `var`.
+- Module pattern: each API resource is a constructor function (not a class), attached to the `Api` class instance via `this.<namespace> = new ResourceName(this)`.
+- All async API calls return a **jQuery `$.ajax` promise** (via `AjaxRequest` / `RequestUtils.js`). Do not use `fetch` or `axios` in `src/`.
+- Keep JSDoc comments on every public method following the existing `@namespace` / `@memberof` / `@param` / `@return` pattern so `documentation build` continues to work.
+
+## Adding a New API Module
+1. Create `src/Api/MyResource.js` following the existing constructor-function pattern.
+2. Import and instantiate it in `src/Api/Api.js` (follow the existing import list and `this.myResource = new MyResource(this)` in the constructor).
+3. Add corresponding tests in `test/api_tests/MyResourceTests.js` using QUnit + `ApiHelper`.
+4. Add TypeScript declarations in `types/bimplus-websdk.d.ts`.
+5. Document with JSDoc `@namespace`/`@memberof api` tags.
+
+## Testing
+- Framework: **QUnit** running inside **Karma** (browser-based).
+- Tests are integration tests that call the real Bimplus dev API — they require `BIM_PASS` env variable.
+- Run all tests: `npm test`
+- Run headless Chrome: `npm run test-chrome-headless`
+- Test helpers live in `test/helpers/ApiHelper.js`. Use `ApiHelper` to set up team/project context before assertions.
+- Assert HTTP error responses with `assertHttpStatusText(assert, e, "Bad Request")` (global helper injected by Karma).
+
+## Build
+- Dev build (with source maps): `npm run build`
+- Production build (minified): `npm run build-prod`
+- Lint: `npm run eslint`
+- Output format: UMD, entry `src/Api/Api.js` → `dist/bimplus-websdk.js`
+- Webpack config split: `webpack.common.js` (shared), `webpack.dev.js`, `webpack.prod.js`
+
+## Documentation
+- Generate HTML docs: `npm run build-doc`
+- Generate Markdown: `npm run build-docMd`
+- Every public method in `src/Api/*.js` must pass `documentation lint` (`npm run lint-doc`) — keep JSDoc valid.
+
+## Key Conventions
+- URL helpers: use `api.getApiTeamUrl()` for team-scoped endpoints, `api.getApiUrl()` for global endpoints.
+- Query parameters are passed as `{ queryParams: { key: value } }` in the `params` argument to `api.request.get()`.
+- Chunked upload/download helpers (`getChunked`, `putChunked`) are in `AjaxRequest.js` — use them for large payloads.
+- IDB caching is opt-in via `IDBCache.js` / `CachedRequest.js`; do not add caching logic directly to resource modules.
+- Global flags `window.BIMPLUS_SDK_ENABLE_CACHE`, `window.BIMPLUS_SDK_LOG_API_CALLS`, `window.BIMPLUS_SDK_DISABLE_ETAG`, `window.BIMPLUS_SDK_PENDING_REQUESTS` are intentional public hooks — do not remove them.
+
+## What to Avoid
+- Do not introduce new runtime dependencies without discussing it first; the current dependency footprint (`async`, `dexie`, `jquery`) is intentionally minimal.
+- Do not convert constructor functions to ES6 `class` syntax — this would break backward compatibility with consumers using the UMD bundle.
+- Do not add `async/await` to `src/` code without ensuring Babel transpilation handles it (check `@babel/plugin-transform-runtime` config).
+- Do not commit credentials, tokens, or real GUIDs from the test environment into source files.

package/.github/instructions/api-core.instructions.md

@@ -0,0 +1,144 @@
+---
+applyTo: "websdk/src/Api/Api.js, websdk/src/Api/AjaxRequest.js, websdk/src/Api/RequestUtils.js"
+---
+
+# Bimplus WebSDK — Core API & Request Layer
+
+## Api Class Initialization
+
+```js
+import { Api, createDefaultConfig } from './src/Api/Api';
+
+const config = createDefaultConfig('dev'); // 'dev' | 'stage' | 'prod' (default)
+const api = new Api(config);
+```
+
+### `createDefaultConfig(env?)` Environments
+
+| `env` value | Host |
+|---|---|
+| `'dev'` | `api-dev.bimplus.net` |
+| `'stage'` | `api-stage.bimplus.net` |
+| `'prod'` / omitted | `api.bimplus.net` |
+
+### Config Shape
+
+```json
+{
+  "protocol": "https://",
+  "host": "api-dev.bimplus.net",
+  "version": "v2",
+  "cache": false
+}
+```
+
+- `version` defaults to `'v2'` if omitted from a custom config object.
+- `cache: true` enables IDB-backed caching via `CachedRequest`. If IndexedDB is not supported by the browser, it falls back silently to `AjaxRequest` with a console warning.
+
+---
+
+## Authentication & Setup Flow
+
+After constructing `Api`, always perform these three steps before calling any resource API:
+
+```js
+// 1. Obtain a token
+const auth = await api.authorize.post(username, password, applicationId);
+
+// 2. Set the token (token type 'BimPlus' is the standard)
+api.setAccessTokenAndType(auth.access_token, 'BimPlus');
+
+// 3. Set the team context (required for all team-scoped endpoints)
+api.setTeamSlug('my-team-slug');
+```
+
+| Method | Purpose |
+|---|---|
+| `api.setAccessToken(token)` | Sets token only |
+| `api.setTokenType(type)` | Sets token type only |
+| `api.setAccessTokenAndType(token, type)` | Sets both at once (preferred) |
+| `api.setTeamSlug(slug)` | Required before any team-scoped request |
+| `api.getTeamSlug()` | Returns current team slug |
+| `api.getAccessToken()` | Returns current token |
+| `api.getAccessTokenAndType()` | Returns `{ token, tokenType }` |
+
+---
+
+## URL Building
+
+| Method | Example output |
+|---|---|
+| `api.getApiUrl()` | `https://api-dev.bimplus.net/v2/` |
+| `api.getApiTeamUrl()` | `https://api-dev.bimplus.net/v2/my-team-slug/` |
+
+- `getApiTeamUrl()` logs a `console.error` if `teamSlug` is not set — it does **not** throw.
+- Use `getApiUrl()` for global (non-team-scoped) endpoints: `authorize`, `auth-forgot`, `cross-token`, `validate`, `administration/backups`, `.well-known/openid-configuration`.
+- Use `getApiTeamUrl()` for all other endpoints (projects, objects, divisions, issues, etc.).
+
+---
+
+## Request Layer (`AjaxRequest`)
+
+All resource modules call `api.request.get / put / post / del`. The signatures are:
+
+```js
+api.request.get(url, ajaxParams?)
+api.request.put(url, data, ajaxParams?)
+api.request.post(url, data, ajaxParams?)
+api.request.del(url, data?, ajaxParams?)
+```
+
+### `ajaxParams` shape
+
+```js
+{
+  queryParams: { key: 'value' },        // appended as URL query string
+  contentType: 'application/json; charset=utf-8', // default
+  dataType: 'json',                     // default; set to null for non-JSON responses
+  processData: false,                   // default
+  eTag: '<etag-value>',                 // adds If-None-Match header (unless BIMPLUS_SDK_DISABLE_ETAG is set)
+  headers: { 'X-Custom': 'val' },       // extra request headers
+  useXMLHttpRequest: true,              // use XMLHttpRequest instead of $.ajax (e.g. binary/streaming)
+  responseType: 'arraybuffer',          // XHR binary response type
+  xhrUploadProgress: function(e) {},    // upload progress callback for XHR
+}
+```
+
+### Chunked helpers
+
+Use these for large payloads — never implement custom chunking inside resource modules:
+
+```js
+api.request.getChunked(url, ajaxConfig)       // chunked GET
+api.request.putChunked(url, data, ajaxConfig) // chunked PUT
+```
+
+---
+
+## Global Window Flags
+
+All flags are optional. They must be set **before** any request is made.
+
+| Flag | Type | Effect |
+|---|---|---|
+| `window.BIMPLUS_SDK_ENABLE_CACHE` | `boolean` | Enables jQuery `$.ajax` browser-level cache |
+| `window.BIMPLUS_SDK_LOG_API_CALLS` | `boolean` | Console-logs every request URL + parsed response |
+| `window.BIMPLUS_SDK_DISABLE_ETAG` | `boolean` | Suppresses `If-None-Match` header even when `eTag` is set in ajaxParams |
+| `window.BIMPLUS_SDK_PENDING_REQUESTS` | `number` | Incremented on request start, decremented on complete — useful to track in-flight requests |
+| `window.BIMPLUS_SDK_ENABLE_DEBUG_LOGS` | `boolean` | Logs token, tokenType, teamSlug, and config to console during `Api` initialization |
+
+> `BIMPLUS_SDK_ENABLE_DEBUG_LOGS` is intentional — do not remove it.
+
+---
+
+## Models vs. Divisions Naming
+
+The Bimplus REST API uses the term **"divisions"** for what the SDK exposes as **`api.models`**. This is a legacy naming mismatch:
+
+| SDK namespace | REST endpoint |
+|---|---|
+| `api.models.get(modelId)` | `GET .../divisions/:id` |
+| `api.models.getRevisions(divisionId)` | `GET .../divisions/:id/revisions` |
+| `api.models.getDisciplines(divisionId)` | `GET .../divisions/:id/disciplines` |
+
+Always use `api.models` in SDK code. Use `divisionId` as the parameter name for the ID (not `modelId`) when the underlying endpoint says `divisions`.

package/.github/instructions/project-attributes.instructions.md

@@ -0,0 +1,172 @@
+---
+applyTo: "websdk/src/Api/Projects.js, websdk/test/api_tests/Project*.js, websdk/types/bimplus-websdk.d.ts"
+---
+
+# Bimplus Project Attributes
+
+## Core Project Object (`projects.get()`)
+
+When retrieving a project via `api.projects.get(id?)`, the returned JSON object contains these fields:
+
+```json
+{
+  "id":          "<guid>",
+  "name":        "My Project",
+  "shortDescr":  "Short project description",
+  "address":     "Street, City, Country",
+  "teamSlug":    "my-team-slug",
+  "teamName":    "My Team",
+  "rights":      { ... },
+  "disciplines": [ ... ]
+}
+```
+
+| Field | Type | Notes |
+|---|---|---|
+| `id` | `string (Guid)` | Unique project identifier |
+| `name` | `string` | Display name of the project |
+| `shortDescr` | `string` | Short description / subtitle |
+| `address` | `string` | Physical address of the project |
+| `teamSlug` | `string` | URL slug of the owning team |
+| `teamName` | `string` | Display name of the owning team |
+| `rights` | `object` | Current user's access rights on this project |
+| `disciplines` | `array` | List of model disciplines; omitted when `noDisciplines=true` |
+
+> `disciplines` can be suppressed by calling `api.projects.get(id, true)` for performance on large project lists.
+
+---
+
+## Extended Attribute Object (`objects.getAttributes(projectId, "", projectId, "")`)
+
+The full project attribute set — as shown on the BimPortal project detail page — is retrieved via:
+
+```js
+const projectAttributes = await api.objects.getAttributes(projectId, "", projectId, "");
+```
+
+### Top-level shape
+
+```json
+{
+  "id":                      "<project guid>",
+  "name":                    "My Project",
+  "type":                    "Project",
+  "elementtyp":              "8d27ae6d-3c9a-4201-8a4d-bf0225861788",
+  "attributes":              { ... },
+  "localizedAttributeGroups": { ... }
+}
+```
+
+| Field | Value / Notes |
+|---|---|
+| `id` | Project GUID |
+| `name` | Project name |
+| `type` | Always `"Project"` |
+| `elementtyp` | Fixed GUID `8d27ae6d-3c9a-4201-8a4d-bf0225861788` — identifies the project element type in Bimplus |
+| `attributes` | Map of attribute groups (see below) |
+| `localizedAttributeGroups` | Localized display names for each group key |
+
+### Attribute groups (`attributes`)
+
+The `attributes` object always contains exactly **7 groups**:
+
+| Group key | Description |
+|---|---|
+| `address` | Physical address fields of the project |
+| `others` | Miscellaneous project settings (see details below) |
+| `project` | Core project metadata |
+| `project contact` | Contact person information |
+| `project meeting` | Project meeting data |
+| `project offset` | Internal coordinate system offset (x, y, z) |
+| `project statistics` | Computed statistics and counters |
+
+### Individual attribute shape
+
+Each entry inside a group is keyed by a localized attribute name and has the following structure:
+
+```json
+{
+  "id":          "<guid>",
+  "name":        "Offset X",
+  "description": "Offset X",
+  "group":       "project offset",
+  "type":        "double",
+  "unit":        "m",
+  "value":       100
+}
+```
+
+| Field | Notes |
+|---|---|
+| `id` | Stable GUID — use this for lookups, not the name (names can be localized) |
+| `name` | Human-readable attribute name |
+| `description` | Longer description of the attribute |
+| `group` | The group this attribute belongs to |
+| `type` | Data type: `"string"`, `"double"`, `"boolean"`, `"guid"`, etc. |
+| `unit` | Unit string, e.g. `"m"` — may be absent for non-numeric types |
+| `value` | The current value |
+
+---
+
+## Well-known Attribute GUIDs
+
+Use `id` for reliable lookups — never match by `name` alone (names are localizable).
+
+### `project offset` group — internal offsets
+
+| Attribute | GUID | Type | Unit |
+|---|---|---|---|
+| Offset X | `e276009f-f637-43ef-90ee-8e145e8dc41c` | `double` | `m` |
+| Offset Y | `2e112c8a-47fb-40ba-b7b3-3f601daa127c` | `double` | `m` |
+| Offset Z | `d0cbf9eb-25b2-4443-b23d-8c67396822e8` | `double` | `m` |
+
+### `others` group — user-defined global offsets and settings
+
+| Attribute | GUID | Type | Unit |
+|---|---|---|---|
+| Δ x (global coordinate x) | `ecea05de-9450-48f8-a8f2-f1de32b7cd5c` | `double` | `m` |
+| Δ y (global coordinate y) | `6d0e5735-2c05-4b24-90c2-663ba234a6f8` | `double` | `m` |
+| Δ z (global coordinate z) | `43b6bb07-0b1f-49ff-b226-33befba937e2` | `double` | `m` |
+| Default language for BCF export | `2ae6edb6-bfbd-4ce6-ae7e-7dcd7b0abc2e` | `string` | — |
+| Project currency | `513d2bdd-f994-46b6-a629-0a5e694893a5` | `string` | — |
+| Properties template | `3d7404a8-f2e7-4418-b87a-daf1597cfb49` | `guid` | — |
+| RestrictMemberAccessInPortal | `f4437afc-c55b-4227-9d97-89035ce8dafd` | `boolean` | — |
+| Units (Units and Dimensions) | `a907b2b1-91f2-46e6-a045-7fee485c458b` | `guid` | — |
+
+---
+
+## Related Sub-resources (via `api.projects.*`)
+
+The following child resources are accessible directly from a project ID:
+
+| Method | Endpoint pattern | Returns |
+|---|---|---|
+| `getModels(projectId)` | `.../projects/:id/divisions` | Array of model/discipline objects |
+| `getMembers(projectId)` | `.../projects/:id/members` | Array of `{ member, group }` objects |
+| `getPins(projectId)` | `.../projects/:id/pins` | Array of pin objects |
+| `getSpots(projectId)` | `.../projects/:id/pins` | Alias for pins |
+| `getAttachments(projectId, revision?, queryParams?)` | `.../projects/:id/attachments` | Array of attachment objects |
+| `getTopology(projectId)` | `.../projects/:id/topology` | Topology tree with `children` |
+| `getComments(projectId)` | `.../projects/:id/comments` | Array of comment objects |
+| `getHyperlinks(projectId)` | `.../projects/:id/hyperlinks` | Array of hyperlink objects |
+| `getIssues(projectId, filterScene?, thumbnailUrl?)` | `.../projects/:id/issues` | Array of issue/task objects |
+| `getIssuesShortInfo(projectId)` | `.../projects/:id/issues?shortinfo=true` | Array of summarized issue info |
+| `getSlideshows(projectId)` | `.../projects/:id/slideshows` | Array of slideshow objects |
+| `getThumbnail(thumbnailId)` | `.../thumbnail/:id` | Thumbnail data |
+| `getProjectInfo(projectId)` | `.../projects/:id` | Same shape as `projects.get(id)` |
+
+---
+
+## Writable Project Fields (POST / PUT)
+
+When creating (`projects.post(data)`) or updating (`projects.put(id, data)`) a project, pass a JSON-stringified object with:
+
+```json
+{
+  "name":       "My Awesome Building",
+  "shortDescr": "Example description",
+  "address":    "Street, City"
+}
+```
+
+The response returns the full project object including the server-assigned `id` and `teamSlug`.

package/.github/instructions/test-conventions.instructions.md

@@ -0,0 +1,209 @@
+---
+applyTo: "websdk/test/api_tests/**, websdk/test/helpers/**"
+---
+
+# Bimplus WebSDK — Test Conventions
+
+## Test Framework
+
+- **QUnit** + **Karma** (browser-based integration tests against the real Bimplus API)
+- Tests are **not** unit tests — they require a live API connection and valid credentials
+- One test file per API module, named `<Module>Tests.js` in `test/api_tests/`
+
+---
+
+## ApiHelper Setup
+
+Import `ApiHelper` at the top of every test file:
+
+```js
+import { ApiHelper } from '../helpers/ApiHelper';
+```
+
+Instantiate it inside each `QUnit.test` callback (not at module level):
+
+```js
+const helper = new ApiHelper();
+```
+
+### Team and Project Context
+
+Always set context before calling resource APIs:
+
+```js
+await helper.setTeamByName();             // uses helper.defaultTeam
+await helper.setTeamByName('My Team');    // specific team by display name
+
+const projectId = await helper.setProjectByName();              // uses helper.BasicProject.name
+const projectId = await helper.setProjectByName(null, 'Proj'); // specific project name
+```
+
+- `setTeamByName` performs `login()` automatically, looks up the team by name, and calls `api.setTeamSlug()`.
+- `setProjectByName` also calls `setTeamByName` internally — no need to call both.
+- Both return the resolved `id`.
+
+### Accessing the API Instance
+
+```js
+helper.api.projects.get(projectId);
+helper.api.models.get(modelId);
+```
+
+---
+
+## Environment Variables
+
+| Variable | Environment | Purpose |
+|---|---|---|
+| `BIM_PASS` | `dev` | Password for `bimplus.web.sdk@allplan.com` on dev |
+| `BIM_PASS_STAGE` | `stage` | Password for the same user on stage |
+| `BIM_PASS_PROD` | `prod` | Password for the same user on prod |
+
+The environment is auto-detected by `ApiHelper` from the Karma `host` config. Never hard-code passwords.
+
+---
+
+## Test Fixture Constants
+
+All GUIDs for test data are exposed on the `ApiHelper` instance. Always reference these — never hard-code GUIDs in test files.
+
+### Shared fixtures (environment-independent)
+
+| Property | Description |
+|---|---|
+| `helper.BasicProject` | Main project for most object/topology/filter tests |
+| `helper.BasicProject.projectId` | Project GUID |
+| `helper.BasicProject.divisionId_m1` | Division (model) GUID for model `m1` |
+| `helper.BasicProject.wallId_m1` | Object GUID for a wall in model `m1` |
+| `helper.BasicProject.doorId_m1` | Object GUID for a door in model `m1` |
+| `helper.BasicProjectTest` | Project used for create/update/delete project tests |
+| `helper.BasicProjectWithOffsets` | Project with known coordinate offsets |
+| `helper.BasicStructuresTest` | Project for structure tests |
+| `helper.BasicMarkupTests` | Project for annotation/markup tests |
+| `helper.BasicSlideshowTests` | Project for slideshow tests |
+| `helper.undefinedId` | `"00000000-0000-0000-0000-000000000000"` — use for "not found" tests |
+| `helper.dummyId` | `"AAAAAAAA-0000-AAAA-0000-000000000000"` — use for invalid-ID tests |
+
+### Environment-specific fixtures (differ between dev / stage / prod)
+
+| Property | Description |
+|---|---|
+| `helper.BasicModelTest` | Project with 3 revisions (rev1Id, rev2Id, rev3Id) |
+| `helper.BasicImportTest` | Project + model for IFC import tests |
+| `helper.BasicOverlayTests` | Project with overlays and versioned attachments |
+| `helper.BasicConnexisTest` | Project for structural Connexis tests |
+| `helper.BasicWorkflowTest` | Project for workflow template tests |
+
+### User constants
+
+| Property | Value |
+|---|---|
+| `helper.defaultEMail` | `bimplus.web.sdk@allplan.com` |
+| `helper.defaultTeam` | Team display name for the current environment |
+| `helper.defaultTeamSlug` | URL slug of the test team |
+| `helper.defaultTeamId` | GUID of the test team |
+| `helper.defaultAppId` | `5F43560D-9B0C-4F3C-85CB-B5721D098F7B` (shared across envs) |
+| `helper.invitationUserEmail` | `bimplus.renderer.test@allplan.com` — for member/message tests |
+
+---
+
+## QUnit Test Pattern
+
+```js
+QUnit.module("api_tests/MyResourceTests", function () {
+
+  QUnit.test("Get resource", async function (assert) {
+    assert.expect(2); // always declare expected assertion count up front
+
+    const helper = new ApiHelper();
+    await helper.setTeamByName();
+
+    const result = await helper.api.myResource.get();
+    assert.ok(result.length > 0);
+    assert.ok(result[0].name);
+  });
+
+  QUnit.test("Handle HTTP error", async function (assert) {
+    assert.expect(2);
+
+    const helper = new ApiHelper();
+    await helper.setTeamByName();
+
+    try {
+      await helper.api.myResource.get(helper.undefinedId);
+      assert.ok(false, 'Should have thrown');
+    } catch (e) {
+      assertHttpStatusText(assert, e, "Not Found"); // global injected by Karma — do NOT import it
+    }
+  });
+
+});
+```
+
+Key rules:
+- **Always** call `assert.expect(N)` at the start of each test
+- Use `async function` + `await` — no `.then()` chains or callbacks in test body
+- Module name must match the file path exactly: `"api_tests/MyResourceTests"`
+- `assertHttpStatusText` is a **Karma-injected global** — never import it
+- Use `helper.undefinedId` or `helper.dummyId` to trigger expected HTTP errors, not random strings
+
+---
+
+## Specialist Test Helpers
+
+For complex resource domains, additional helpers exist in `test/helpers/`:
+
+| Helper | Used for |
+|---|---|
+| `AnnotationsHelper` | Creating annotation payloads |
+| `LabelsHelper` | Creating label payloads with object IDs |
+| `DimensionsHelper` | Creating dimension payloads with object IDs |
+| `MultipartFormDataHelper` | Building multipart/form-data for file uploads |
+| `MessagesHelper` | Cleaning up all messages for a user before tests run |
+
+Import them alongside `ApiHelper` when needed:
+
+```js
+import { LabelsHelper } from '../helpers/LabelsHelper';
+```
+
+---
+
+## Message Cleanup in `beforeEach`
+
+Some backend services (notably `ExportWorkerService`) deliver notification messages to `defaultUserId` **asynchronously** after an operation completes (e.g. an IFC export triggered by `ExportServiceTests`). Because test files run alphabetically and `ExportServiceTests` (E) runs well before `InvitationsTests` (I) and `MessagesTests` (M), these delayed notifications can arrive in the user's inbox during a later test, causing false failures on empty-inbox assertions.
+
+**Any test module that asserts on message counts must call `deleteAllMessages` in its `beforeEach`:**
+
+```js
+import { ApiHelper } from '../helpers/ApiHelper';
+import { deleteAllMessages } from '../helpers/MessagesHelper';
+
+QUnit.module("api_tests/MyTests", function (hooks) {
+
+  hooks.beforeEach(async function () {
+    const helper = new ApiHelper();
+    await helper.setProjectByName();
+    await deleteAllMessages(helper.api, helper.defaultUserId);
+  });
+
+});
+```
+
+`deleteAllMessages(api, userId)` fetches all four message endpoints in parallel — `getUserMessages` (inbox), `getSentUserMessages` (sent), `getSentGroupMessages` (group-sent), and `getUserDashboardMessages` (dashboard) — deduplicates IDs across all four, and deletes everything found in parallel. It exits only after **two consecutive empty checks**, confirming a stable empty state. This prevents the race where a background-service message arrives in the window between an empty fetch and the next test assertion. A 1-second pause separates each pass (up to 5 attempts total).
+
+> **Do not** replicate this loop inline. Always use `deleteAllMessages` from `MessagesHelper`.
+
+### When to find messages by ID, not by index
+
+When verifying that a newly created message appears in a list alongside possible system messages, always locate it by its known ID rather than assuming array position:
+
+```js
+// Wrong — breaks when system messages sort before the test message
+assert.equal(messages[0].topic, "MY_TOPIC");
+
+// Correct
+const testMessage = messages.find((m) => m.id === createdMessage.id);
+assert.ok(testMessage, "test message found in sent messages");
+assert.equal(testMessage.topic, "MY_TOPIC");
+```