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.
- package/README.md +169 -0
- package/bundle/index.cjs +3484 -2149
- package/bundle/index.cjs.map +1 -1
- package/bundle/index.mjs +3484 -2149
- package/bundle/index.mjs.map +1 -1
- package/dist/clients/AasDiscoveryClient.d.ts +12 -5
- package/dist/clients/AasDiscoveryClient.js +104 -27
- package/dist/clients/AasRegistryClient.d.ts +32 -10
- package/dist/clients/AasRegistryClient.js +211 -61
- package/dist/clients/AasRepositoryClient.d.ts +231 -60
- package/dist/clients/AasRepositoryClient.js +1021 -353
- package/dist/clients/AasxFileClient.d.ts +29 -3
- package/dist/clients/AasxFileClient.js +122 -31
- package/dist/clients/ConceptDescriptionRepositoryClient.d.ts +14 -4
- package/dist/clients/ConceptDescriptionRepositoryClient.js +127 -35
- package/dist/clients/SubmodelRegistryClient.d.ts +14 -4
- package/dist/clients/SubmodelRegistryClient.js +117 -27
- package/dist/clients/SubmodelRepositoryClient.d.ts +339 -58
- package/dist/clients/SubmodelRepositoryClient.js +913 -269
- package/dist/generated/AasDiscoveryService/models/index.d.ts +2 -2
- package/dist/generated/AasRegistryService/apis/AssetAdministrationShellRegistryAPIApi.d.ts +1 -1
- package/dist/generated/AasRegistryService/apis/AssetAdministrationShellRegistryAPIApi.js +1 -1
- package/dist/generated/AasRegistryService/apis/DescriptionAPIApi.d.ts +1 -1
- package/dist/generated/AasRegistryService/apis/DescriptionAPIApi.js +1 -1
- package/dist/generated/AasRegistryService/index.d.ts +1 -1
- package/dist/generated/AasRegistryService/index.js +1 -1
- package/dist/generated/AasRegistryService/models/index.d.ts +3 -3
- package/dist/generated/AasRepositoryService/apis/AssetAdministrationShellRepositoryAPIApi.d.ts +3 -3
- package/dist/generated/AasRepositoryService/apis/AssetAdministrationShellRepositoryAPIApi.js +1 -1
- package/dist/generated/AasRepositoryService/apis/DescriptionAPIApi.d.ts +1 -1
- package/dist/generated/AasRepositoryService/apis/DescriptionAPIApi.js +1 -1
- package/dist/generated/AasRepositoryService/apis/SerializationAPIApi.d.ts +1 -1
- package/dist/generated/AasRepositoryService/apis/SerializationAPIApi.js +1 -1
- package/dist/generated/AasRepositoryService/index.d.ts +1 -1
- package/dist/generated/AasRepositoryService/index.js +1 -1
- package/dist/generated/AasRepositoryService/models/index.d.ts +7 -7
- package/dist/generated/AasxFileService/apis/AASXFileServerAPIApi.d.ts +5 -3
- package/dist/generated/AasxFileService/apis/AASXFileServerAPIApi.js +6 -0
- package/dist/generated/AasxFileService/apis/DescriptionAPIApi.d.ts +26 -0
- package/dist/generated/AasxFileService/apis/DescriptionAPIApi.js +40 -0
- package/dist/generated/AasxFileService/apis/index.d.ts +1 -0
- package/dist/generated/AasxFileService/apis/index.js +1 -0
- package/dist/generated/AasxFileService/models/index.d.ts +45 -0
- package/dist/generated/ConceptDescriptionRepositoryService/models/index.d.ts +2 -2
- package/dist/generated/SubmodelRegistryService/models/index.d.ts +2 -2
- package/dist/generated/SubmodelRepositoryService/models/index.d.ts +9 -9
- package/dist/generated/runtime.js +7 -0
- package/dist/lib/apiConfig.d.ts +2 -1
- package/dist/lib/apiConfig.js +27 -2
- package/dist/lib/conditionalRequests.d.ts +28 -0
- package/dist/lib/conditionalRequests.js +55 -0
- package/dist/lib/errorHandler.js +13 -2
- package/dist/models/api.d.ts +40 -2
- package/dist/services/AasService.d.ts +34 -4
- package/dist/services/AasService.js +159 -33
- package/dist/services/SubmodelService.d.ts +34 -4
- package/dist/services/SubmodelService.js +168 -28
- package/package.json +14 -3
- package/dist/generated/AasRegistryService/runtime.d.ts +0 -181
- package/dist/generated/AasRegistryService/runtime.js +0 -326
- package/dist/generated/AasRepositoryService/runtime.d.ts +0 -181
- 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',
|