basyx-typescript-sdk 2.2.4 → 2.3.0

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 (62) hide show
  1. package/README.md +169 -0
  2. package/bundle/index.cjs +3484 -2149
  3. package/bundle/index.cjs.map +1 -1
  4. package/bundle/index.mjs +3484 -2149
  5. package/bundle/index.mjs.map +1 -1
  6. package/dist/clients/AasDiscoveryClient.d.ts +12 -5
  7. package/dist/clients/AasDiscoveryClient.js +104 -27
  8. package/dist/clients/AasRegistryClient.d.ts +32 -10
  9. package/dist/clients/AasRegistryClient.js +211 -61
  10. package/dist/clients/AasRepositoryClient.d.ts +231 -60
  11. package/dist/clients/AasRepositoryClient.js +1021 -353
  12. package/dist/clients/AasxFileClient.d.ts +29 -3
  13. package/dist/clients/AasxFileClient.js +122 -31
  14. package/dist/clients/ConceptDescriptionRepositoryClient.d.ts +14 -4
  15. package/dist/clients/ConceptDescriptionRepositoryClient.js +127 -35
  16. package/dist/clients/SubmodelRegistryClient.d.ts +14 -4
  17. package/dist/clients/SubmodelRegistryClient.js +117 -27
  18. package/dist/clients/SubmodelRepositoryClient.d.ts +339 -58
  19. package/dist/clients/SubmodelRepositoryClient.js +913 -269
  20. package/dist/generated/AasDiscoveryService/models/index.d.ts +2 -2
  21. package/dist/generated/AasRegistryService/apis/AssetAdministrationShellRegistryAPIApi.d.ts +1 -1
  22. package/dist/generated/AasRegistryService/apis/AssetAdministrationShellRegistryAPIApi.js +1 -1
  23. package/dist/generated/AasRegistryService/apis/DescriptionAPIApi.d.ts +1 -1
  24. package/dist/generated/AasRegistryService/apis/DescriptionAPIApi.js +1 -1
  25. package/dist/generated/AasRegistryService/index.d.ts +1 -1
  26. package/dist/generated/AasRegistryService/index.js +1 -1
  27. package/dist/generated/AasRegistryService/models/index.d.ts +3 -3
  28. package/dist/generated/AasRepositoryService/apis/AssetAdministrationShellRepositoryAPIApi.d.ts +3 -3
  29. package/dist/generated/AasRepositoryService/apis/AssetAdministrationShellRepositoryAPIApi.js +1 -1
  30. package/dist/generated/AasRepositoryService/apis/DescriptionAPIApi.d.ts +1 -1
  31. package/dist/generated/AasRepositoryService/apis/DescriptionAPIApi.js +1 -1
  32. package/dist/generated/AasRepositoryService/apis/SerializationAPIApi.d.ts +1 -1
  33. package/dist/generated/AasRepositoryService/apis/SerializationAPIApi.js +1 -1
  34. package/dist/generated/AasRepositoryService/index.d.ts +1 -1
  35. package/dist/generated/AasRepositoryService/index.js +1 -1
  36. package/dist/generated/AasRepositoryService/models/index.d.ts +7 -7
  37. package/dist/generated/AasxFileService/apis/AASXFileServerAPIApi.d.ts +5 -3
  38. package/dist/generated/AasxFileService/apis/AASXFileServerAPIApi.js +6 -0
  39. package/dist/generated/AasxFileService/apis/DescriptionAPIApi.d.ts +26 -0
  40. package/dist/generated/AasxFileService/apis/DescriptionAPIApi.js +40 -0
  41. package/dist/generated/AasxFileService/apis/index.d.ts +1 -0
  42. package/dist/generated/AasxFileService/apis/index.js +1 -0
  43. package/dist/generated/AasxFileService/models/index.d.ts +45 -0
  44. package/dist/generated/ConceptDescriptionRepositoryService/models/index.d.ts +2 -2
  45. package/dist/generated/SubmodelRegistryService/models/index.d.ts +2 -2
  46. package/dist/generated/SubmodelRepositoryService/models/index.d.ts +9 -9
  47. package/dist/generated/runtime.js +7 -0
  48. package/dist/lib/apiConfig.d.ts +2 -1
  49. package/dist/lib/apiConfig.js +27 -2
  50. package/dist/lib/conditionalRequests.d.ts +28 -0
  51. package/dist/lib/conditionalRequests.js +55 -0
  52. package/dist/lib/errorHandler.js +13 -2
  53. package/dist/models/api.d.ts +40 -2
  54. package/dist/services/AasService.d.ts +34 -4
  55. package/dist/services/AasService.js +159 -33
  56. package/dist/services/SubmodelService.d.ts +34 -4
  57. package/dist/services/SubmodelService.js +168 -28
  58. package/package.json +14 -3
  59. package/dist/generated/AasRegistryService/runtime.d.ts +0 -181
  60. package/dist/generated/AasRegistryService/runtime.js +0 -326
  61. package/dist/generated/AasRepositoryService/runtime.d.ts +0 -181
  62. package/dist/generated/AasRepositoryService/runtime.js +0 -326
package/README.md CHANGED
@@ -15,10 +15,12 @@ High-level orchestration services:
15
15
  - Create, read, update, delete AAS with automatic registry synchronization
16
16
  - Fetch AAS with their submodels in a single call
17
17
  - Automatic endpoint resolution and fallback handling
18
+ - Optional registry resolution warnings and strict fail-fast mode for list operations
18
19
  - **SubmodelService**: Unified API for Submodel operations across registry and repository
19
20
  - Create, read, update, delete Submodels with automatic registry synchronization
20
21
  - Flexible endpoint-based retrieval
21
22
  - Automatic fallback to repository when registry unavailable
23
+ - Optional registry resolution warnings and strict fail-fast mode for list operations
22
24
 
23
25
  Clients for the AAS API components:
24
26
 
@@ -30,6 +32,9 @@ Clients for the AAS API components:
30
32
  - AAS Discovery Service
31
33
  - AASX File Service
32
34
 
35
+ All clients support [conditional requests](#conditional-requests-etag) (`ETag`, `If-Match`, `If-None-Match`) for
36
+ optimistic concurrency.
37
+
33
38
  Utility functions for working with AAS data:
34
39
 
35
40
  - Utils for Descriptors
@@ -78,6 +83,95 @@ Use `.nvmrc` to align local Node.js with CI:
78
83
  nvm use
79
84
  ```
80
85
 
86
+ ## Integration Test Engine
87
+
88
+ The repository includes a CLI test engine that reuses the integration suites for infrastructure components. The user
89
+ provides a component ID and endpoint URL, and the engine produces selectable reports with passed checks and failed
90
+ checks including reasons.
91
+
92
+ The engine targets unsecured endpoints and does not start Docker by itself.
93
+
94
+ ### Available Components
95
+
96
+ - `aas-repository`
97
+ - `submodel-repository`
98
+ - `concept-description-repository`
99
+ - `aas-registry`
100
+ - `submodel-registry`
101
+ - `aas-discovery`
102
+ - `aasx-file-server`
103
+
104
+ List components:
105
+
106
+ ```bash
107
+ pnpm test:engine:list-components
108
+ ```
109
+
110
+ Run against one component endpoint:
111
+
112
+ ```bash
113
+ pnpm test:engine --component submodel-repository --url http://localhost:8082
114
+ ```
115
+
116
+ Select output formats (`console`, `json`, `junit`, `markdown`):
117
+
118
+ ```bash
119
+ pnpm test:engine --component aas-repository --url http://localhost:8081 --report console,json,junit,markdown
120
+ ```
121
+
122
+ Strict known-issues mode (waived known issues become failures):
123
+
124
+ ```bash
125
+ pnpm test:engine --component aas-discovery --url http://localhost:8086 --strict-known-issues
126
+ ```
127
+
128
+ Use a custom artifact directory:
129
+
130
+ ```bash
131
+ pnpm test:engine --component aasx-file-server --url http://localhost:8087 --report-dir coverage/test-engine
132
+ ```
133
+
134
+ ### Report Behavior
135
+
136
+ - `console`: run summary plus failed checks and reasons, including endpoint and response snippets when available.
137
+ - `json`: machine-readable report for workflow processing, including failure diagnostics such as request
138
+ method/endpoint, request body summary, response status, response body snippet, and trace source for integration-test
139
+ failures.
140
+ - `junit`: CI-compatible XML artifact; integration-test failure entries include endpoint and response context in the
141
+ failure message.
142
+ - `markdown`: shareable summary document with failure diagnostics and copyable cURL replay blocks for integration-test
143
+ failures.
144
+
145
+ Failure diagnostics are captured only in test-engine mode and are sanitized:
146
+
147
+ - Authorization and cookie-style headers are redacted.
148
+ - Large request/response bodies are truncated to compact snippets.
149
+ - Multipart/binary replay commands use real relative file names when available; otherwise placeholders are emitted.
150
+
151
+ Exit code behavior:
152
+
153
+ - `0` if all non-waived checks pass.
154
+ - non-zero if any integration check fails or OpenAPI critical findings exist.
155
+ - in strict mode, waived known issues also fail the run.
156
+
157
+ ### Known Backend Deviations (Integration)
158
+
159
+ The integration suites include some checks that are currently waived or adapted due to backend behavior that does not
160
+ fully match expected API behavior.
161
+
162
+ Observed and tracked:
163
+
164
+ - `submodel-repository` `GetAllSubmodels-Path` can return an empty `result` array even when a fresh submodel has been
165
+ created in the same run. The test now validates success and response shape, but does not require `result.length > 0`.
166
+ - `submodel-repository` value-only cursor not-found behavior is tracked as `known-specification-bug`.
167
+
168
+ Maintenance rule for new findings:
169
+
170
+ - If a backend deviation is confirmed, annotate the affected test with a short reason (`known-backend-bug` or
171
+ `known-specification-bug`), and add a short note in this section.
172
+ - Prefer narrowing assertions to contract-safe checks (status and shape) instead of asserting unstable payload details.
173
+ - Keep strict mode available (`--strict-known-issues`) so waived issues are still visible in CI when needed.
174
+
81
175
  ## Import Styles
82
176
 
83
177
  The SDK supports multiple import styles for flexibility:
@@ -133,6 +227,8 @@ async function getAllShells() {
133
227
  const client = new AasRepositoryClient();
134
228
  const configuration = new Configuration({
135
229
  basePath: 'http://localhost:8081',
230
+ // Optional: automatically sends `Authorization: Bearer <token>` on requests
231
+ accessToken: async () => 'your-oidc-access-token',
136
232
  });
137
233
 
138
234
  const response = await client.getAllAssetAdministrationShells({ configuration });
@@ -145,6 +241,60 @@ async function getAllShells() {
145
241
  }
146
242
  ```
147
243
 
244
+ `Configuration.accessToken` is applied automatically by the runtime. You only need middleware if you want custom auth
245
+ logic beyond bearer token injection.
246
+
247
+ ### Conditional Requests (ETag)
248
+
249
+ Clients report the `ETag` of a response as `etag` and accept the conditional request headers of RFC 9110, so that
250
+ concurrent changes are detected instead of silently overwritten. The entity tag is opaque: pass it back unchanged.
251
+ Servers that send no `ETag` leave `etag` `undefined`.
252
+
253
+ | Option | Methods | Header |
254
+ | ------------- | ---------------------------------------------------------------------- | --------------- |
255
+ | `ifMatch` | `put*`, `patch*`, `delete*`, `post*` below a resource, operation calls | `If-Match` |
256
+ | `ifNoneMatch` | `put*` (use `*` to only create), `get*` of a resource or its parts | `If-None-Match` |
257
+
258
+ ```typescript
259
+ import { Configuration, SubmodelRepositoryClient } from 'basyx-typescript-sdk';
260
+
261
+ const client = new SubmodelRepositoryClient();
262
+ const configuration = new Configuration({ basePath: 'http://localhost:8082' });
263
+ const submodelIdentifier = 'https://example.com/ids/sm/1';
264
+
265
+ const read = await client.getSubmodelById({ configuration, submodelIdentifier });
266
+ if (read.success) {
267
+ const update = await client.patchSubmodelElementByPathValueOnly({
268
+ configuration,
269
+ submodelIdentifier,
270
+ idShortPath: 'Temperature',
271
+ submodelElementValue: '21.5',
272
+ ifMatch: read.etag,
273
+ });
274
+
275
+ if (!update.success && update.preconditionFailed) {
276
+ // 412: the Submodel was changed by someone else. Reload, merge and retry.
277
+ }
278
+ // update.etag is the new entity tag for the next conditional write
279
+ }
280
+
281
+ // Revalidate a cached representation
282
+ const revalidated = await client.getSubmodelById({ configuration, submodelIdentifier, ifNoneMatch: cachedEtag });
283
+ if (revalidated.success && revalidated.notModified) {
284
+ // 304: keep using the cached Submodel
285
+ }
286
+ ```
287
+
288
+ - Failed results have `preconditionFailed: true` for `412 Precondition Failed` and `preconditionRequired: true` for
289
+ `428 Precondition Required` (the server requires `If-Match`).
290
+ - A read returns `{ success: true, notModified: true, statusCode: 304 }` without `data` only if `ifNoneMatch` is passed;
291
+ the result type includes this case only then.
292
+ - `AasService` and `SubmodelService` return the `etag` of the shell or Submodel on reads and accept `ifMatch` for
293
+ `updateAas`, `deleteAas`, `updateSubmodel` and `deleteSubmodel`. The condition applies to the repository; with
294
+ `ifMatch`, deletes remove the repository resource before the registry descriptor and require the repository
295
+ configuration.
296
+ - Calls without these options behave as before.
297
+
148
298
  ### Using the AasService (High-level API)
149
299
 
150
300
  ```typescript
@@ -179,8 +329,17 @@ if (createResult.success) {
179
329
  const listResult = await service.getAasList();
180
330
  if (listResult.success) {
181
331
  console.log('All shells:', listResult.data.shells);
332
+ // Optional warnings for descriptors that could not be resolved
333
+ if (listResult.data.warnings?.length) {
334
+ console.warn('Registry resolution warnings:', listResult.data.warnings);
335
+ }
182
336
  }
183
337
 
338
+ // Strict mode: fail immediately if any registry descriptor cannot be resolved
339
+ const strictListResult = await service.getAasList({
340
+ strictRegistryResolution: true,
341
+ });
342
+
184
343
  // Get AAS by ID (uses registry endpoint if available)
185
344
  const getResult = await service.getAasById({
186
345
  aasIdentifier: 'https://example.com/ids/aas/my-aas',
@@ -352,8 +511,18 @@ const listResult = await service.getSubmodelList({ preferRegistry: true });
352
511
  if (listResult.success) {
353
512
  console.log('All submodels:', listResult.data.submodels);
354
513
  console.log('Fetched from:', listResult.data.source); // 'registry' or 'repository'
514
+ // Optional warnings for descriptors that could not be resolved
515
+ if (listResult.data.warnings?.length) {
516
+ console.warn('Registry resolution warnings:', listResult.data.warnings);
517
+ }
355
518
  }
356
519
 
520
+ // Strict mode: fail immediately if any registry descriptor cannot be resolved
521
+ const strictSubmodelListResult = await service.getSubmodelList({
522
+ preferRegistry: true,
523
+ strictRegistryResolution: true,
524
+ });
525
+
357
526
  // Get Submodel by ID (uses registry endpoint if available)
358
527
  const getResult = await service.getSubmodelById({
359
528
  submodelIdentifier: 'https://example.com/ids/sm/my-submodel',