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.
- package/README.md +115 -0
- package/bundle/index.cjs +2479 -1814
- package/bundle/index.cjs.map +1 -1
- package/bundle/index.mjs +2479 -1814
- package/bundle/index.mjs.map +1 -1
- package/dist/clients/AasDiscoveryClient.d.ts +3 -2
- package/dist/clients/AasDiscoveryClient.js +78 -20
- package/dist/clients/AasRegistryClient.d.ts +4 -2
- package/dist/clients/AasRegistryClient.js +153 -45
- package/dist/clients/AasRepositoryClient.d.ts +73 -16
- package/dist/clients/AasRepositoryClient.js +682 -263
- package/dist/clients/AasxFileClient.d.ts +18 -0
- package/dist/clients/AasxFileClient.js +100 -25
- package/dist/clients/ConceptDescriptionRepositoryClient.d.ts +3 -1
- package/dist/clients/ConceptDescriptionRepositoryClient.js +93 -29
- package/dist/clients/SubmodelRegistryClient.d.ts +3 -1
- package/dist/clients/SubmodelRegistryClient.js +91 -21
- package/dist/clients/SubmodelRepositoryClient.d.ts +229 -22
- package/dist/clients/SubmodelRepositoryClient.js +689 -201
- 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/errorHandler.js +13 -2
- package/dist/models/api.d.ts +4 -2
- package/dist/services/AasService.d.ts +21 -1
- package/dist/services/AasService.js +114 -26
- package/dist/services/SubmodelService.d.ts +21 -1
- package/dist/services/SubmodelService.js +119 -21
- 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
|
|
|
@@ -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',
|