basyx-typescript-sdk 2.2.4 → 2.2.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 (58) hide show
  1. package/README.md +115 -0
  2. package/bundle/index.cjs +2479 -1814
  3. package/bundle/index.cjs.map +1 -1
  4. package/bundle/index.mjs +2479 -1814
  5. package/bundle/index.mjs.map +1 -1
  6. package/dist/clients/AasDiscoveryClient.d.ts +3 -2
  7. package/dist/clients/AasDiscoveryClient.js +78 -20
  8. package/dist/clients/AasRegistryClient.d.ts +4 -2
  9. package/dist/clients/AasRegistryClient.js +153 -45
  10. package/dist/clients/AasRepositoryClient.d.ts +73 -16
  11. package/dist/clients/AasRepositoryClient.js +682 -263
  12. package/dist/clients/AasxFileClient.d.ts +18 -0
  13. package/dist/clients/AasxFileClient.js +100 -25
  14. package/dist/clients/ConceptDescriptionRepositoryClient.d.ts +3 -1
  15. package/dist/clients/ConceptDescriptionRepositoryClient.js +93 -29
  16. package/dist/clients/SubmodelRegistryClient.d.ts +3 -1
  17. package/dist/clients/SubmodelRegistryClient.js +91 -21
  18. package/dist/clients/SubmodelRepositoryClient.d.ts +229 -22
  19. package/dist/clients/SubmodelRepositoryClient.js +689 -201
  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/errorHandler.js +13 -2
  49. package/dist/models/api.d.ts +4 -2
  50. package/dist/services/AasService.d.ts +21 -1
  51. package/dist/services/AasService.js +114 -26
  52. package/dist/services/SubmodelService.d.ts +21 -1
  53. package/dist/services/SubmodelService.js +119 -21
  54. package/package.json +14 -3
  55. package/dist/generated/AasRegistryService/runtime.d.ts +0 -181
  56. package/dist/generated/AasRegistryService/runtime.js +0 -326
  57. package/dist/generated/AasRepositoryService/runtime.d.ts +0 -181
  58. 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
 
@@ -78,6 +80,95 @@ Use `.nvmrc` to align local Node.js with CI:
78
80
  nvm use
79
81
  ```
80
82
 
83
+ ## Integration Test Engine
84
+
85
+ The repository includes a CLI test engine that reuses the integration suites for infrastructure components. The user
86
+ provides a component ID and endpoint URL, and the engine produces selectable reports with passed checks and failed
87
+ checks including reasons.
88
+
89
+ The engine targets unsecured endpoints and does not start Docker by itself.
90
+
91
+ ### Available Components
92
+
93
+ - `aas-repository`
94
+ - `submodel-repository`
95
+ - `concept-description-repository`
96
+ - `aas-registry`
97
+ - `submodel-registry`
98
+ - `aas-discovery`
99
+ - `aasx-file-server`
100
+
101
+ List components:
102
+
103
+ ```bash
104
+ pnpm test:engine:list-components
105
+ ```
106
+
107
+ Run against one component endpoint:
108
+
109
+ ```bash
110
+ pnpm test:engine --component submodel-repository --url http://localhost:8082
111
+ ```
112
+
113
+ Select output formats (`console`, `json`, `junit`, `markdown`):
114
+
115
+ ```bash
116
+ pnpm test:engine --component aas-repository --url http://localhost:8081 --report console,json,junit,markdown
117
+ ```
118
+
119
+ Strict known-issues mode (waived known issues become failures):
120
+
121
+ ```bash
122
+ pnpm test:engine --component aas-discovery --url http://localhost:8086 --strict-known-issues
123
+ ```
124
+
125
+ Use a custom artifact directory:
126
+
127
+ ```bash
128
+ pnpm test:engine --component aasx-file-server --url http://localhost:8087 --report-dir coverage/test-engine
129
+ ```
130
+
131
+ ### Report Behavior
132
+
133
+ - `console`: run summary plus failed checks and reasons, including endpoint and response snippets when available.
134
+ - `json`: machine-readable report for workflow processing, including failure diagnostics such as request
135
+ method/endpoint, request body summary, response status, response body snippet, and trace source for integration-test
136
+ failures.
137
+ - `junit`: CI-compatible XML artifact; integration-test failure entries include endpoint and response context in the
138
+ failure message.
139
+ - `markdown`: shareable summary document with failure diagnostics and copyable cURL replay blocks for integration-test
140
+ failures.
141
+
142
+ Failure diagnostics are captured only in test-engine mode and are sanitized:
143
+
144
+ - Authorization and cookie-style headers are redacted.
145
+ - Large request/response bodies are truncated to compact snippets.
146
+ - Multipart/binary replay commands use real relative file names when available; otherwise placeholders are emitted.
147
+
148
+ Exit code behavior:
149
+
150
+ - `0` if all non-waived checks pass.
151
+ - non-zero if any integration check fails or OpenAPI critical findings exist.
152
+ - in strict mode, waived known issues also fail the run.
153
+
154
+ ### Known Backend Deviations (Integration)
155
+
156
+ The integration suites include some checks that are currently waived or adapted due to backend behavior that does not
157
+ fully match expected API behavior.
158
+
159
+ Observed and tracked:
160
+
161
+ - `submodel-repository` `GetAllSubmodels-Path` can return an empty `result` array even when a fresh submodel has been
162
+ created in the same run. The test now validates success and response shape, but does not require `result.length > 0`.
163
+ - `submodel-repository` value-only cursor not-found behavior is tracked as `known-specification-bug`.
164
+
165
+ Maintenance rule for new findings:
166
+
167
+ - If a backend deviation is confirmed, annotate the affected test with a short reason (`known-backend-bug` or
168
+ `known-specification-bug`), and add a short note in this section.
169
+ - Prefer narrowing assertions to contract-safe checks (status and shape) instead of asserting unstable payload details.
170
+ - Keep strict mode available (`--strict-known-issues`) so waived issues are still visible in CI when needed.
171
+
81
172
  ## Import Styles
82
173
 
83
174
  The SDK supports multiple import styles for flexibility:
@@ -133,6 +224,8 @@ async function getAllShells() {
133
224
  const client = new AasRepositoryClient();
134
225
  const configuration = new Configuration({
135
226
  basePath: 'http://localhost:8081',
227
+ // Optional: automatically sends `Authorization: Bearer <token>` on requests
228
+ accessToken: async () => 'your-oidc-access-token',
136
229
  });
137
230
 
138
231
  const response = await client.getAllAssetAdministrationShells({ configuration });
@@ -145,6 +238,9 @@ async function getAllShells() {
145
238
  }
146
239
  ```
147
240
 
241
+ `Configuration.accessToken` is applied automatically by the runtime. You only need middleware if you want custom auth
242
+ logic beyond bearer token injection.
243
+
148
244
  ### Using the AasService (High-level API)
149
245
 
150
246
  ```typescript
@@ -179,8 +275,17 @@ if (createResult.success) {
179
275
  const listResult = await service.getAasList();
180
276
  if (listResult.success) {
181
277
  console.log('All shells:', listResult.data.shells);
278
+ // Optional warnings for descriptors that could not be resolved
279
+ if (listResult.data.warnings?.length) {
280
+ console.warn('Registry resolution warnings:', listResult.data.warnings);
281
+ }
182
282
  }
183
283
 
284
+ // Strict mode: fail immediately if any registry descriptor cannot be resolved
285
+ const strictListResult = await service.getAasList({
286
+ strictRegistryResolution: true,
287
+ });
288
+
184
289
  // Get AAS by ID (uses registry endpoint if available)
185
290
  const getResult = await service.getAasById({
186
291
  aasIdentifier: 'https://example.com/ids/aas/my-aas',
@@ -352,8 +457,18 @@ const listResult = await service.getSubmodelList({ preferRegistry: true });
352
457
  if (listResult.success) {
353
458
  console.log('All submodels:', listResult.data.submodels);
354
459
  console.log('Fetched from:', listResult.data.source); // 'registry' or 'repository'
460
+ // Optional warnings for descriptors that could not be resolved
461
+ if (listResult.data.warnings?.length) {
462
+ console.warn('Registry resolution warnings:', listResult.data.warnings);
463
+ }
355
464
  }
356
465
 
466
+ // Strict mode: fail immediately if any registry descriptor cannot be resolved
467
+ const strictSubmodelListResult = await service.getSubmodelList({
468
+ preferRegistry: true,
469
+ strictRegistryResolution: true,
470
+ });
471
+
357
472
  // Get Submodel by ID (uses registry endpoint if available)
358
473
  const getResult = await service.getSubmodelById({
359
474
  submodelIdentifier: 'https://example.com/ids/sm/my-submodel',