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
@@ -7,6 +7,12 @@ export interface SubmodelServiceConfig {
7
7
  submodelRepositoryConfig?: Configuration;
8
8
  conceptDescriptionRepositoryConfig?: Configuration;
9
9
  }
10
+ export interface SubmodelListResolutionWarning {
11
+ submodelIdentifier?: string;
12
+ endpoint?: string;
13
+ errorType: string;
14
+ message: string;
15
+ }
10
16
  /**
11
17
  * SubmodelService combines Submodel Registry, Submodel Repository, and Concept Description Repository clients
12
18
  * to provide higher-level functionality for working with Submodels.
@@ -33,14 +39,20 @@ export declare class SubmodelService {
33
39
  *
34
40
  * @param options Object containing:
35
41
  * - preferRegistry?: Whether to prefer registry over repository (default: true)
42
+ * - strictRegistryResolution?: Whether registry endpoint resolution failures should fail immediately (default: false)
36
43
  * - limit?: Maximum number of elements to retrieve
37
44
  * - cursor?: Pagination cursor
38
45
  * - includeConceptDescriptions?: Whether to fetch concept descriptions (default: false)
39
46
  *
40
- * @returns Either `{ success: true; data: { submodels, source, conceptDescriptions? } }` or `{ success: false; error: ... }`.
47
+ * @returns Either
48
+ * `{ success: true; data: { submodels, source, conceptDescriptions?, warnings? } }`
49
+ * or `{ success: false; error: ... }`.
50
+ * When `strictRegistryResolution` is `true`, unresolved registry descriptors return
51
+ * `RegistryResolutionError` with `warnings`.
41
52
  */
42
53
  getSubmodelList(options?: {
43
54
  preferRegistry?: boolean;
55
+ strictRegistryResolution?: boolean;
44
56
  limit?: number;
45
57
  cursor?: string;
46
58
  includeConceptDescriptions?: boolean;
@@ -48,6 +60,7 @@ export declare class SubmodelService {
48
60
  submodels: Submodel[];
49
61
  source: 'registry' | 'repository';
50
62
  conceptDescriptions?: ConceptDescription[];
63
+ warnings?: SubmodelListResolutionWarning[];
51
64
  }, any>>;
52
65
  /**
53
66
  * Retrieves a Submodel by ID.
@@ -61,7 +74,8 @@ export declare class SubmodelService {
61
74
  * - useRegistryEndpoint?: Whether to try registry endpoint first (default: true)
62
75
  * - includeConceptDescriptions?: Whether to fetch concept descriptions (default: false)
63
76
  *
64
- * @returns Either `{ success: true; data: { submodel, descriptor?, conceptDescriptions? } }` or `{ success: false; error: ... }`.
77
+ * @returns Either `{ success: true; data: { submodel, descriptor?, conceptDescriptions? }; etag? }` or `{ success: false; error: ... }`.
78
+ * `etag` is the entity tag of the Submodel, if the repository sends one.
65
79
  */
66
80
  getSubmodelById(options: {
67
81
  submodelIdentifier: string;
@@ -99,7 +113,8 @@ export declare class SubmodelService {
99
113
  * - endpoint: The endpoint URL (format: http://host/submodels/{base64EncodedId})
100
114
  * - includeConceptDescriptions?: Whether to fetch concept descriptions (default: false)
101
115
  *
102
- * @returns Either `{ success: true; data: { submodel, conceptDescriptions? } }` or `{ success: false; error: ... }`.
116
+ * @returns Either `{ success: true; data: { submodel, conceptDescriptions? }; etag? }` or `{ success: false; error: ... }`.
117
+ * `etag` is the entity tag of the Submodel, if the repository sends one.
103
118
  */
104
119
  getSubmodelByEndpoint(options: {
105
120
  endpoint: string;
@@ -108,6 +123,13 @@ export declare class SubmodelService {
108
123
  submodel: Submodel;
109
124
  conceptDescriptions?: ConceptDescription[];
110
125
  }, any>>;
126
+ /**
127
+ * Creates a repository configuration for an endpoint while preserving auth and middleware.
128
+ *
129
+ * @param basePath The endpoint base path to target
130
+ * @returns Configuration with endpoint basePath plus repository auth/settings
131
+ */
132
+ private createRepositoryEndpointConfiguration;
111
133
  /**
112
134
  * Creates a Submodel and optionally registers it in the registry.
113
135
  *
@@ -138,12 +160,15 @@ export declare class SubmodelService {
138
160
  * @param options Object containing:
139
161
  * - submodel: The updated Submodel
140
162
  * - updateInRegistry?: Whether to update the descriptor in the registry (default: true)
163
+ * - ifMatch?: Sent as `If-Match` header with the repository update; if the Submodel has changed, the update fails
164
+ * with `preconditionFailed` and the registry is not updated
141
165
  *
142
166
  * @returns Either `{ success: true; data: { submodel, descriptor? } }` or `{ success: false; error: ... }`.
143
167
  */
144
168
  updateSubmodel(options: {
145
169
  submodel: Submodel;
146
170
  updateInRegistry?: boolean;
171
+ ifMatch?: string;
147
172
  }): Promise<ApiResult<{
148
173
  submodel: Submodel;
149
174
  descriptor?: SubmodelDescriptor;
@@ -152,18 +177,23 @@ export declare class SubmodelService {
152
177
  * Deletes a Submodel and optionally removes it from the registry.
153
178
  *
154
179
  * This method removes the descriptor from the registry first (if requested),
155
- * then deletes the Submodel from the repository.
180
+ * then deletes the Submodel from the repository. With `ifMatch`, the Submodel is deleted from the repository
181
+ * first, so that a failed precondition leaves the descriptor in the registry.
156
182
  *
157
183
  * @param options Object containing:
158
184
  * - submodelIdentifier: The Submodel identifier to remove
159
185
  * - deleteFromRegistry?: Whether to delete from registry (default: true)
186
+ * - ifMatch?: Sent as `If-Match` header with the repository delete; if the Submodel has changed, the delete fails
187
+ * with `preconditionFailed`. Requires the repository configuration.
160
188
  *
161
189
  * @returns Either `{ success: true; data: void }` or `{ success: false; error: ... }`.
162
190
  */
163
191
  deleteSubmodel(options: {
164
192
  submodelIdentifier: string;
165
193
  deleteFromRegistry?: boolean;
194
+ ifMatch?: string;
166
195
  }): Promise<ApiResult<void, any>>;
196
+ private deleteSubmodelFromRepository;
167
197
  /**
168
198
  * Helper method to create a Submodel descriptor from a Submodel.
169
199
  * Populates descriptor fields from the submodel including metadata and endpoint configuration.
@@ -4,6 +4,7 @@ import { SubmodelRegistryClient } from '../clients/SubmodelRegistryClient';
4
4
  import { SubmodelRepositoryClient } from '../clients/SubmodelRepositoryClient';
5
5
  import { Configuration } from '../generated/runtime';
6
6
  import { base64Decode, base64Encode } from '../lib/base64Url';
7
+ import { pickConditionalErrorFields } from '../lib/conditionalRequests';
7
8
  import { SubmodelDescriptor } from '../models/Descriptors';
8
9
  /**
9
10
  * SubmodelService combines Submodel Registry, Submodel Repository, and Concept Description Repository clients
@@ -38,15 +39,22 @@ export class SubmodelService {
38
39
  *
39
40
  * @param options Object containing:
40
41
  * - preferRegistry?: Whether to prefer registry over repository (default: true)
42
+ * - strictRegistryResolution?: Whether registry endpoint resolution failures should fail immediately (default: false)
41
43
  * - limit?: Maximum number of elements to retrieve
42
44
  * - cursor?: Pagination cursor
43
45
  * - includeConceptDescriptions?: Whether to fetch concept descriptions (default: false)
44
46
  *
45
- * @returns Either `{ success: true; data: { submodels, source, conceptDescriptions? } }` or `{ success: false; error: ... }`.
47
+ * @returns Either
48
+ * `{ success: true; data: { submodels, source, conceptDescriptions?, warnings? } }`
49
+ * or `{ success: false; error: ... }`.
50
+ * When `strictRegistryResolution` is `true`, unresolved registry descriptors return
51
+ * `RegistryResolutionError` with `warnings`.
46
52
  */
47
53
  async getSubmodelList(options) {
48
54
  const preferRegistry = options?.preferRegistry ?? true;
55
+ const strictRegistryResolution = options?.strictRegistryResolution ?? false;
49
56
  const includeConceptDescriptions = options?.includeConceptDescriptions ?? false;
57
+ let registryResolutionWarnings = [];
50
58
  // Try registry first if configured and preferred
51
59
  if (preferRegistry && this.submodelRegistryConfig) {
52
60
  const registryResult = await this.submodelRegistryClient.getAllSubmodelDescriptors({
@@ -56,29 +64,84 @@ export class SubmodelService {
56
64
  });
57
65
  if (registryResult.success) {
58
66
  const descriptors = registryResult.data.result;
59
- // Fetch submodels from their endpoints
60
- const submodelPromises = descriptors.map(async (descriptor) => {
67
+ // Resolve submodels from descriptor endpoints and aggregate warnings deterministically.
68
+ const descriptorResults = await Promise.all(descriptors.map(async (descriptor) => {
69
+ if (!descriptor.id) {
70
+ return {
71
+ submodel: null,
72
+ warning: {
73
+ errorType: 'MissingDescriptorId',
74
+ message: 'Submodel descriptor does not contain an id and cannot be resolved',
75
+ },
76
+ };
77
+ }
61
78
  const endpoint = descriptor.endpoints?.[0]?.protocolInformation?.href;
62
79
  if (!endpoint) {
63
- return null;
80
+ return {
81
+ submodel: null,
82
+ warning: {
83
+ submodelIdentifier: descriptor.id,
84
+ errorType: 'MissingEndpoint',
85
+ message: 'Submodel descriptor has no endpoint and cannot be resolved',
86
+ },
87
+ };
64
88
  }
65
89
  const submodelResult = await this.getSubmodelByEndpoint({ endpoint });
66
- return submodelResult.success ? submodelResult.data.submodel : null;
67
- });
68
- const submodels = (await Promise.all(submodelPromises)).filter((sm) => sm !== null);
69
- // Fetch concept descriptions if requested
70
- let conceptDescriptions;
71
- if (includeConceptDescriptions) {
72
- conceptDescriptions = await this.fetchConceptDescriptionsForSubmodels(submodels);
90
+ if (submodelResult.success) {
91
+ return { submodel: submodelResult.data.submodel };
92
+ }
93
+ const resolutionError = submodelResult.error;
94
+ return {
95
+ submodel: null,
96
+ warning: {
97
+ submodelIdentifier: descriptor.id,
98
+ endpoint,
99
+ errorType: resolutionError?.errorType || 'EndpointResolutionError',
100
+ message: resolutionError?.message ||
101
+ resolutionError?.messages?.[0]?.text ||
102
+ 'Failed to resolve Submodel from descriptor endpoint',
103
+ },
104
+ };
105
+ }));
106
+ const submodels = descriptorResults
107
+ .map((result) => result.submodel)
108
+ .filter((sm) => sm !== null);
109
+ const warnings = descriptorResults
110
+ .map((result) => result.warning)
111
+ .filter((warning) => warning !== undefined);
112
+ if (strictRegistryResolution && warnings.length > 0) {
113
+ return {
114
+ success: false,
115
+ error: {
116
+ errorType: 'RegistryResolutionError',
117
+ message: 'Failed to resolve one or more Submodel descriptors via registry endpoints',
118
+ warnings,
119
+ },
120
+ };
73
121
  }
74
- return {
75
- success: true,
76
- data: {
77
- submodels,
78
- source: 'registry',
79
- ...(conceptDescriptions && { conceptDescriptions }),
80
- },
81
- };
122
+ // If registry descriptors exist but none were resolvable, fall back to repository when possible.
123
+ if (warnings.length > 0 && submodels.length === 0 && this.submodelRepositoryConfig) {
124
+ registryResolutionWarnings = warnings;
125
+ }
126
+ else {
127
+ // Fetch concept descriptions if requested
128
+ let conceptDescriptions;
129
+ if (includeConceptDescriptions) {
130
+ conceptDescriptions = await this.fetchConceptDescriptionsForSubmodels(submodels);
131
+ }
132
+ return {
133
+ success: true,
134
+ data: {
135
+ submodels,
136
+ source: 'registry',
137
+ ...(conceptDescriptions && { conceptDescriptions }),
138
+ ...(warnings.length > 0 && { warnings }),
139
+ },
140
+ };
141
+ }
142
+ }
143
+ else {
144
+ registryResolutionWarnings = [];
82
145
  }
83
146
  }
84
147
  // Fall back to repository if registry failed or not configured
@@ -101,6 +164,7 @@ export class SubmodelService {
101
164
  submodels,
102
165
  source: 'repository',
103
166
  ...(conceptDescriptions && { conceptDescriptions }),
167
+ ...(registryResolutionWarnings.length > 0 && { warnings: registryResolutionWarnings }),
104
168
  },
105
169
  };
106
170
  }
@@ -126,7 +190,8 @@ export class SubmodelService {
126
190
  * - useRegistryEndpoint?: Whether to try registry endpoint first (default: true)
127
191
  * - includeConceptDescriptions?: Whether to fetch concept descriptions (default: false)
128
192
  *
129
- * @returns Either `{ success: true; data: { submodel, descriptor?, conceptDescriptions? } }` or `{ success: false; error: ... }`.
193
+ * @returns Either `{ success: true; data: { submodel, descriptor?, conceptDescriptions? }; etag? }` or `{ success: false; error: ... }`.
194
+ * `etag` is the entity tag of the Submodel, if the repository sends one.
130
195
  */
131
196
  async getSubmodelById(options) {
132
197
  const { submodelIdentifier, useRegistryEndpoint = true, includeConceptDescriptions = false } = options;
@@ -154,6 +219,7 @@ export class SubmodelService {
154
219
  conceptDescriptions: submodelResult.data.conceptDescriptions,
155
220
  }),
156
221
  },
222
+ etag: submodelResult.etag,
157
223
  };
158
224
  }
159
225
  }
@@ -188,6 +254,7 @@ export class SubmodelService {
188
254
  descriptor: undefined,
189
255
  ...(conceptDescriptions && { conceptDescriptions }),
190
256
  },
257
+ etag: submodelResult.etag,
191
258
  };
192
259
  }
193
260
  return { success: false, error: submodelResult.error };
@@ -245,7 +312,8 @@ export class SubmodelService {
245
312
  * - endpoint: The endpoint URL (format: http://host/submodels/{base64EncodedId})
246
313
  * - includeConceptDescriptions?: Whether to fetch concept descriptions (default: false)
247
314
  *
248
- * @returns Either `{ success: true; data: { submodel, conceptDescriptions? } }` or `{ success: false; error: ... }`.
315
+ * @returns Either `{ success: true; data: { submodel, conceptDescriptions? }; etag? }` or `{ success: false; error: ... }`.
316
+ * `etag` is the entity tag of the Submodel, if the repository sends one.
249
317
  */
250
318
  async getSubmodelByEndpoint(options) {
251
319
  const { endpoint, includeConceptDescriptions = false } = options;
@@ -263,9 +331,21 @@ export class SubmodelService {
263
331
  }
264
332
  const [, baseUrl, encodedId] = match;
265
333
  // Decode the ID
266
- const submodelIdentifier = base64Decode(encodedId);
334
+ let submodelIdentifier;
335
+ try {
336
+ submodelIdentifier = base64Decode(encodedId);
337
+ }
338
+ catch {
339
+ return {
340
+ success: false,
341
+ error: {
342
+ errorType: 'InvalidEndpoint',
343
+ message: 'Endpoint contains an invalid Base64URL-encoded Submodel identifier.',
344
+ },
345
+ };
346
+ }
267
347
  // Create configuration for the endpoint
268
- const config = new Configuration({ basePath: baseUrl });
348
+ const config = this.createRepositoryEndpointConfiguration(baseUrl);
269
349
  // Fetch the submodel
270
350
  const submodelResult = await this.submodelRepositoryClient.getSubmodelById({
271
351
  configuration: config,
@@ -286,8 +366,32 @@ export class SubmodelService {
286
366
  submodel,
287
367
  ...(conceptDescriptions && { conceptDescriptions }),
288
368
  },
369
+ etag: submodelResult.etag,
289
370
  };
290
371
  }
372
+ /**
373
+ * Creates a repository configuration for an endpoint while preserving auth and middleware.
374
+ *
375
+ * @param basePath The endpoint base path to target
376
+ * @returns Configuration with endpoint basePath plus repository auth/settings
377
+ */
378
+ createRepositoryEndpointConfiguration(basePath) {
379
+ if (!this.submodelRepositoryConfig) {
380
+ return new Configuration({ basePath });
381
+ }
382
+ return new Configuration({
383
+ basePath,
384
+ fetchApi: this.submodelRepositoryConfig.fetchApi,
385
+ middleware: this.submodelRepositoryConfig.middleware,
386
+ queryParamsStringify: this.submodelRepositoryConfig.queryParamsStringify,
387
+ username: this.submodelRepositoryConfig.username,
388
+ password: this.submodelRepositoryConfig.password,
389
+ apiKey: this.submodelRepositoryConfig.apiKey,
390
+ accessToken: this.submodelRepositoryConfig.accessToken,
391
+ headers: this.submodelRepositoryConfig.headers,
392
+ credentials: this.submodelRepositoryConfig.credentials,
393
+ });
394
+ }
291
395
  /**
292
396
  * Creates a Submodel and optionally registers it in the registry.
293
397
  *
@@ -358,11 +462,13 @@ export class SubmodelService {
358
462
  * @param options Object containing:
359
463
  * - submodel: The updated Submodel
360
464
  * - updateInRegistry?: Whether to update the descriptor in the registry (default: true)
465
+ * - ifMatch?: Sent as `If-Match` header with the repository update; if the Submodel has changed, the update fails
466
+ * with `preconditionFailed` and the registry is not updated
361
467
  *
362
468
  * @returns Either `{ success: true; data: { submodel, descriptor? } }` or `{ success: false; error: ... }`.
363
469
  */
364
470
  async updateSubmodel(options) {
365
- const { submodel, updateInRegistry = true } = options;
471
+ const { submodel, updateInRegistry = true, ifMatch } = options;
366
472
  if (!this.submodelRepositoryConfig) {
367
473
  return {
368
474
  success: false,
@@ -377,9 +483,10 @@ export class SubmodelService {
377
483
  configuration: this.submodelRepositoryConfig,
378
484
  submodelIdentifier: submodel.id,
379
485
  submodel: submodel,
486
+ ifMatch,
380
487
  });
381
488
  if (!submodelResult.success) {
382
- return { success: false, error: submodelResult.error };
489
+ return { success: false, error: submodelResult.error, ...pickConditionalErrorFields(submodelResult) };
383
490
  }
384
491
  // Use the returned submodel if available, otherwise use the input submodel
385
492
  const updatedSubmodel = submodelResult.data || submodel;
@@ -416,16 +523,35 @@ export class SubmodelService {
416
523
  * Deletes a Submodel and optionally removes it from the registry.
417
524
  *
418
525
  * This method removes the descriptor from the registry first (if requested),
419
- * then deletes the Submodel from the repository.
526
+ * then deletes the Submodel from the repository. With `ifMatch`, the Submodel is deleted from the repository
527
+ * first, so that a failed precondition leaves the descriptor in the registry.
420
528
  *
421
529
  * @param options Object containing:
422
530
  * - submodelIdentifier: The Submodel identifier to remove
423
531
  * - deleteFromRegistry?: Whether to delete from registry (default: true)
532
+ * - ifMatch?: Sent as `If-Match` header with the repository delete; if the Submodel has changed, the delete fails
533
+ * with `preconditionFailed`. Requires the repository configuration.
424
534
  *
425
535
  * @returns Either `{ success: true; data: void }` or `{ success: false; error: ... }`.
426
536
  */
427
537
  async deleteSubmodel(options) {
428
- const { submodelIdentifier, deleteFromRegistry = true } = options;
538
+ const { submodelIdentifier, deleteFromRegistry = true, ifMatch } = options;
539
+ // A conditional delete must not remove the descriptor if the precondition fails or cannot be checked
540
+ if (ifMatch) {
541
+ if (!this.submodelRepositoryConfig) {
542
+ return {
543
+ success: false,
544
+ error: {
545
+ errorType: 'ConfigurationError',
546
+ message: 'Repository configuration required for a conditional delete',
547
+ },
548
+ };
549
+ }
550
+ const repositoryResult = await this.deleteSubmodelFromRepository(submodelIdentifier, ifMatch);
551
+ if (!repositoryResult.success) {
552
+ return repositoryResult;
553
+ }
554
+ }
429
555
  // Remove from registry first if configured and requested
430
556
  if (deleteFromRegistry && this.submodelRegistryConfig) {
431
557
  const registryResult = await this.submodelRegistryClient.deleteSubmodelDescriptorById({
@@ -437,13 +563,27 @@ export class SubmodelService {
437
563
  }
438
564
  }
439
565
  // Remove from repository
566
+ if (!ifMatch) {
567
+ const repositoryResult = await this.deleteSubmodelFromRepository(submodelIdentifier);
568
+ if (!repositoryResult.success) {
569
+ return repositoryResult;
570
+ }
571
+ }
572
+ return { success: true, data: undefined };
573
+ }
574
+ async deleteSubmodelFromRepository(submodelIdentifier, ifMatch) {
440
575
  if (this.submodelRepositoryConfig) {
441
576
  const repositoryResult = await this.submodelRepositoryClient.deleteSubmodelById({
442
577
  configuration: this.submodelRepositoryConfig,
443
578
  submodelIdentifier,
579
+ ifMatch,
444
580
  });
445
581
  if (!repositoryResult.success) {
446
- return { success: false, error: repositoryResult.error };
582
+ return {
583
+ success: false,
584
+ error: repositoryResult.error,
585
+ ...pickConditionalErrorFields(repositoryResult),
586
+ };
447
587
  }
448
588
  }
449
589
  return { success: true, data: undefined };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "basyx-typescript-sdk",
3
- "version": "2.2.4",
3
+ "version": "2.3.0",
4
4
  "description": "BaSyx TypeScript SDK for developing applications and components for the Asset Administration Shell (AAS)",
5
5
  "main": "bundle/index.cjs",
6
6
  "module": "bundle/index.mjs",
@@ -36,6 +36,16 @@
36
36
  "test:watch": "vitest",
37
37
  "test:unit": "vitest run --project unit-tests",
38
38
  "test:integration": "vitest run --project integration-tests",
39
+ "test:engine": "node scripts/test-engine.mjs",
40
+ "test:engine:list-components": "node scripts/test-engine.mjs --list-components",
41
+ "validate:openapi-coverage": "node scripts/validate-openapi-coverage.mjs",
42
+ "validate:openapi-coverage:aasrepo": "node scripts/validate-openapi-coverage.mjs --service aasRepository",
43
+ "validate:openapi-coverage:aasdiscovery": "node scripts/validate-openapi-coverage.mjs --service aasDiscovery",
44
+ "validate:openapi-coverage:aasregistry": "node scripts/validate-openapi-coverage.mjs --service aasRegistry",
45
+ "validate:openapi-coverage:smregistry": "node scripts/validate-openapi-coverage.mjs --service submodelRegistry",
46
+ "validate:openapi-coverage:smrepo": "node scripts/validate-openapi-coverage.mjs --service submodelRepository",
47
+ "validate:openapi-coverage:cdrepo": "node scripts/validate-openapi-coverage.mjs --service conceptDescriptionRepository",
48
+ "validate:openapi-coverage:aasxfileserver": "node scripts/validate-openapi-coverage.mjs --service aasxFileServer",
39
49
  "docs": "typedoc --options typedoc.json",
40
50
  "gen-aasrepo": "openapi-generator-cli generate -i openapi/aasrepository.yaml -g typescript-fetch -o src/generated/AasRepositoryService --additional-properties=withoutRuntimeChecks=true",
41
51
  "gen-submodelrepo": "openapi-generator-cli generate -i openapi/smrepository.yaml -g typescript-fetch -o src/generated/SubmodelRepositoryService --additional-properties=withoutRuntimeChecks=true",
@@ -52,10 +62,10 @@
52
62
  "@aas-core-works/aas-core3.1-typescript": "^1.0.0",
53
63
  "@eslint/js": "^10.0.1",
54
64
  "@openapitools/openapi-generator-cli": "^2.18.4",
55
- "@vitest/coverage-v8": "^4.1.5",
56
65
  "@types/node": "^25.0.0",
57
66
  "@typescript-eslint/eslint-plugin": "^8.59.0",
58
67
  "@typescript-eslint/parser": "^8.59.0",
68
+ "@vitest/coverage-v8": "^4.1.5",
59
69
  "eslint": "^10.2.1",
60
70
  "eslint-config-prettier": "^10.0.1",
61
71
  "eslint-plugin-simple-import-sort": "^13.0.0",
@@ -67,7 +77,8 @@
67
77
  "typedoc": "^0.28.1",
68
78
  "typescript": "^6.0.3",
69
79
  "typescript-eslint": "^8.59.0",
70
- "vitest": "^4.1.5"
80
+ "vitest": "^4.1.5",
81
+ "yaml": "^2.8.3"
71
82
  },
72
83
  "dependencies": {
73
84
  "xmlsax-typescript": "^1.0.0-rc.1"
@@ -1,181 +0,0 @@
1
- /**
2
- * DotAAS Part 2 | HTTP/REST | Asset Administration Shell Registry Service Specification
3
- * The Full Profile of the Asset Administration Shell Registry Service Specification as part of the [Specification of the Asset Administration Shell: Part 2](https://industrialdigitaltwin.org/en/content-hub/aasspecifications). Copyright: Industrial Digital Twin Association (IDTA) 2025
4
- *
5
- * The version of the OpenAPI document: V3.1.1_SSP-001
6
- * Contact: info@idtwin.org
7
- *
8
- * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
9
- * https://openapi-generator.tech
10
- * Do not edit the class manually.
11
- */
12
- export declare const BASE_PATH: string;
13
- export interface ConfigurationParameters {
14
- basePath?: string;
15
- fetchApi?: FetchAPI;
16
- middleware?: Middleware[];
17
- queryParamsStringify?: (params: HTTPQuery) => string;
18
- username?: string;
19
- password?: string;
20
- apiKey?: string | Promise<string> | ((name: string) => string | Promise<string>);
21
- accessToken?: string | Promise<string> | ((name?: string, scopes?: string[]) => string | Promise<string>);
22
- headers?: HTTPHeaders;
23
- credentials?: RequestCredentials;
24
- }
25
- export declare class Configuration {
26
- private configuration;
27
- constructor(configuration?: ConfigurationParameters);
28
- set config(configuration: Configuration);
29
- get basePath(): string;
30
- get fetchApi(): FetchAPI | undefined;
31
- get middleware(): Middleware[];
32
- get queryParamsStringify(): (params: HTTPQuery) => string;
33
- get username(): string | undefined;
34
- get password(): string | undefined;
35
- get apiKey(): ((name: string) => string | Promise<string>) | undefined;
36
- get accessToken(): ((name?: string, scopes?: string[]) => string | Promise<string>) | undefined;
37
- get headers(): HTTPHeaders | undefined;
38
- get credentials(): RequestCredentials | undefined;
39
- }
40
- export declare const DefaultConfig: Configuration;
41
- /**
42
- * This is the base class for all generated API classes.
43
- */
44
- export declare class BaseAPI {
45
- protected configuration: Configuration;
46
- private static readonly jsonRegex;
47
- private middleware;
48
- constructor(configuration?: Configuration);
49
- withMiddleware<T extends BaseAPI>(this: T, ...middlewares: Middleware[]): T;
50
- withPreMiddleware<T extends BaseAPI>(this: T, ...preMiddlewares: Array<Middleware['pre']>): T;
51
- withPostMiddleware<T extends BaseAPI>(this: T, ...postMiddlewares: Array<Middleware['post']>): T;
52
- /**
53
- * Check if the given MIME is a JSON MIME.
54
- * JSON MIME examples:
55
- * application/json
56
- * application/json; charset=UTF8
57
- * APPLICATION/JSON
58
- * application/vnd.company+json
59
- * @param mime - MIME (Multipurpose Internet Mail Extensions)
60
- * @return True if the given MIME is JSON, false otherwise.
61
- */
62
- protected isJsonMime(mime: string | null | undefined): boolean;
63
- protected request(context: RequestOpts, initOverrides?: RequestInit | InitOverrideFunction): Promise<Response>;
64
- private createFetchParams;
65
- private fetchApi;
66
- /**
67
- * Create a shallow clone of `this` by constructing a new instance
68
- * and then shallow cloning data members.
69
- */
70
- private clone;
71
- }
72
- export declare class ResponseError extends Error {
73
- response: Response;
74
- name: "ResponseError";
75
- constructor(response: Response, msg?: string);
76
- }
77
- export declare class FetchError extends Error {
78
- cause: Error;
79
- name: "FetchError";
80
- constructor(cause: Error, msg?: string);
81
- }
82
- export declare class RequiredError extends Error {
83
- field: string;
84
- name: "RequiredError";
85
- constructor(field: string, msg?: string);
86
- }
87
- export declare const COLLECTION_FORMATS: {
88
- csv: string;
89
- ssv: string;
90
- tsv: string;
91
- pipes: string;
92
- };
93
- export type FetchAPI = WindowOrWorkerGlobalScope['fetch'];
94
- export type Json = any;
95
- export type HTTPMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS' | 'HEAD';
96
- export type HTTPHeaders = {
97
- [key: string]: string;
98
- };
99
- export type HTTPQuery = {
100
- [key: string]: string | number | null | boolean | Array<string | number | null | boolean> | Set<string | number | null | boolean> | HTTPQuery;
101
- };
102
- export type HTTPBody = Json | FormData | URLSearchParams;
103
- export type HTTPRequestInit = {
104
- headers?: HTTPHeaders;
105
- method: HTTPMethod;
106
- credentials?: RequestCredentials;
107
- body?: HTTPBody;
108
- };
109
- export type ModelPropertyNaming = 'camelCase' | 'snake_case' | 'PascalCase' | 'original';
110
- export type InitOverrideFunction = (requestContext: {
111
- init: HTTPRequestInit;
112
- context: RequestOpts;
113
- }) => Promise<RequestInit>;
114
- export interface FetchParams {
115
- url: string;
116
- init: RequestInit;
117
- }
118
- export interface RequestOpts {
119
- path: string;
120
- method: HTTPMethod;
121
- headers: HTTPHeaders;
122
- query?: HTTPQuery;
123
- body?: HTTPBody;
124
- }
125
- export declare function querystring(params: HTTPQuery, prefix?: string): string;
126
- export declare function exists(json: any, key: string): boolean;
127
- export declare function canConsumeForm(consumes: Consume[]): boolean;
128
- export interface Consume {
129
- contentType: string;
130
- }
131
- export interface RequestContext {
132
- fetch: FetchAPI;
133
- url: string;
134
- init: RequestInit;
135
- }
136
- export interface ResponseContext {
137
- fetch: FetchAPI;
138
- url: string;
139
- init: RequestInit;
140
- response: Response;
141
- }
142
- export interface ErrorContext {
143
- fetch: FetchAPI;
144
- url: string;
145
- init: RequestInit;
146
- error: unknown;
147
- response?: Response;
148
- }
149
- export interface Middleware {
150
- pre?(context: RequestContext): Promise<FetchParams | void>;
151
- post?(context: ResponseContext): Promise<Response | void>;
152
- onError?(context: ErrorContext): Promise<Response | void>;
153
- }
154
- export interface ApiResponse<T> {
155
- raw: Response;
156
- value(): Promise<T>;
157
- }
158
- export interface ResponseTransformer<T> {
159
- (json: any): T;
160
- }
161
- export declare class JSONApiResponse<T> {
162
- raw: Response;
163
- private transformer;
164
- constructor(raw: Response, transformer?: ResponseTransformer<T>);
165
- value(): Promise<T>;
166
- }
167
- export declare class VoidApiResponse {
168
- raw: Response;
169
- constructor(raw: Response);
170
- value(): Promise<void>;
171
- }
172
- export declare class BlobApiResponse {
173
- raw: Response;
174
- constructor(raw: Response);
175
- value(): Promise<Blob>;
176
- }
177
- export declare class TextApiResponse {
178
- raw: Response;
179
- constructor(raw: Response);
180
- value(): Promise<string>;
181
- }