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
@@ -0,0 +1,55 @@
1
+ function getErrorResponse(err) {
2
+ return err?.response;
3
+ }
4
+ /**
5
+ * Returns the `ETag` header of a response, or `undefined` if the server sent none.
6
+ * The entity tag is opaque and returned unchanged.
7
+ */
8
+ export function getEtag(response) {
9
+ const headers = response?.headers;
10
+ if (typeof headers?.get !== 'function') {
11
+ return undefined;
12
+ }
13
+ return headers.get('ETag') ?? undefined;
14
+ }
15
+ /**
16
+ * Returns the conditional request fields of a failed request: the `ETag` of the error response and the flags for
17
+ * `412 Precondition Failed` and `428 Precondition Required`. Fields that do not apply are omitted.
18
+ */
19
+ export function getConditionalErrorFields(err) {
20
+ const response = getErrorResponse(err);
21
+ const etag = getEtag(response);
22
+ return {
23
+ ...(etag !== undefined && { etag }),
24
+ ...(response?.status === 412 && { preconditionFailed: true }),
25
+ ...(response?.status === 428 && { preconditionRequired: true }),
26
+ };
27
+ }
28
+ /**
29
+ * Returns the conditional request fields of a failed {@link ApiResult}, so that a composite operation can pass them on.
30
+ */
31
+ export function pickConditionalErrorFields(result) {
32
+ return {
33
+ ...(result.etag !== undefined && { etag: result.etag }),
34
+ ...(result.preconditionFailed && { preconditionFailed: true }),
35
+ ...(result.preconditionRequired && { preconditionRequired: true }),
36
+ };
37
+ }
38
+ /**
39
+ * Returns the {@link NotModifiedResult} for a `304 Not Modified` answer to a read with `ifNoneMatch`, or `undefined`
40
+ * for any other error.
41
+ */
42
+ export function getNotModifiedResult(err, ifNoneMatch) {
43
+ const response = getErrorResponse(err);
44
+ if (!ifNoneMatch || response?.status !== 304) {
45
+ return undefined;
46
+ }
47
+ const etag = getEtag(response);
48
+ const result = {
49
+ success: true,
50
+ notModified: true,
51
+ statusCode: 304,
52
+ ...(etag !== undefined && { etag }),
53
+ };
54
+ return result;
55
+ }
@@ -1,4 +1,15 @@
1
1
  import { FetchError, RequiredError, ResponseError } from '../generated/runtime';
2
+ function getResponseStatus(err) {
3
+ const response = err?.response;
4
+ return typeof response?.status === 'number' ? response.status : undefined;
5
+ }
6
+ function isResponseErrorLike(err) {
7
+ return (getResponseStatus(err) !== undefined &&
8
+ typeof err.response?.json === 'function');
9
+ }
10
+ function isRequiredErrorLike(err) {
11
+ return err instanceof RequiredError || err?.name === 'RequiredError';
12
+ }
2
13
  /**
3
14
  * Processes errors from API calls and standardizes them to a Result object
4
15
  * with a consistent messages array following the API spec guidelines.
@@ -22,7 +33,7 @@ export async function handleApiError(err) {
22
33
  text: 'Unknown error',
23
34
  };
24
35
  // Handle different error types
25
- if (err instanceof RequiredError) {
36
+ if (isRequiredErrorLike(err)) {
26
37
  message = {
27
38
  code: '400',
28
39
  messageType: 'Exception',
@@ -30,7 +41,7 @@ export async function handleApiError(err) {
30
41
  timestamp: timestamp,
31
42
  };
32
43
  }
33
- else if (err instanceof ResponseError) {
44
+ else if (err instanceof ResponseError || isResponseErrorLike(err)) {
34
45
  // Try to parse response body for messages
35
46
  const responseBody = err.response;
36
47
  try {
@@ -1,12 +1,50 @@
1
1
  /**
2
2
  * A union for "no-throw" style responses:
3
- * Success => { success: true; data: T }
4
- * Failure => { success: false; error: E }
3
+ * Success => { success: true; data: T; statusCode?: number; etag?: string }
4
+ * Failure => { success: false; error: E; statusCode?: number; etag?: string; preconditionFailed?: boolean; preconditionRequired?: boolean }
5
+ *
6
+ * - `etag`: the opaque entity tag from the `ETag` response header, `undefined` when the server sends none
7
+ * - `preconditionFailed`: `true` for `412 Precondition Failed` (an `If-Match` or `If-None-Match` condition was not met)
8
+ * - `preconditionRequired`: `true` for `428 Precondition Required` (the server requires `If-Match` for the write)
5
9
  */
6
10
  export type ApiResult<T, E> = {
7
11
  success: true;
8
12
  data: T;
13
+ statusCode?: number;
14
+ etag?: string;
15
+ notModified?: false;
9
16
  } | {
10
17
  success: false;
11
18
  error: E;
19
+ statusCode?: number;
20
+ etag?: string;
21
+ preconditionFailed?: boolean;
22
+ preconditionRequired?: boolean;
23
+ };
24
+ /**
25
+ * Result of a read with `ifNoneMatch` whose representation has not changed (`304 Not Modified`).
26
+ * It carries no data; the caller keeps using its cached representation.
27
+ */
28
+ export type NotModifiedResult = {
29
+ success: true;
30
+ notModified: true;
31
+ data?: undefined;
32
+ statusCode: 304;
33
+ etag?: string;
34
+ };
35
+ /**
36
+ * Result of a read that supports `ifNoneMatch`.
37
+ *
38
+ * It is the plain {@link ApiResult} when no `ifNoneMatch` is passed and additionally {@link NotModifiedResult} when
39
+ * it is, so only callers who opt in have to handle `notModified`.
40
+ */
41
+ export type ConditionalApiResult<T, E, IfNoneMatch extends string | undefined = string> = ApiResult<T, E> | (IfNoneMatch extends undefined ? never : NotModifiedResult);
42
+ /**
43
+ * Conditional request headers (RFC 9110). Entity tags are opaque and sent unchanged.
44
+ */
45
+ export type ConditionalRequestHeaders = {
46
+ /** Sent as `If-Match`: an `etag` of a previous response, or `*` */
47
+ ifMatch?: string;
48
+ /** Sent as `If-None-Match`: an `etag` of a previous response, or `*` */
49
+ ifNoneMatch?: string;
12
50
  };
@@ -11,6 +11,12 @@ export interface AasServiceConfig {
11
11
  conceptDescriptionRepositoryConfig?: Configuration;
12
12
  discoveryConfig?: Configuration;
13
13
  }
14
+ export interface AasListResolutionWarning {
15
+ descriptorId?: string;
16
+ endpoint?: string;
17
+ errorType: string;
18
+ message: string;
19
+ }
14
20
  /**
15
21
  * AasService combines and orchestrates multiple clients and services, including:
16
22
  * - AasRegistryClient
@@ -40,15 +46,21 @@ export declare class AasService {
40
46
  *
41
47
  * @param options Object containing:
42
48
  * - preferRegistry?: Whether to prefer registry over repository (default: true)
49
+ * - strictRegistryResolution?: Whether registry endpoint resolution failures should fail immediately (default: false)
43
50
  * - limit?: Maximum number of elements to retrieve
44
51
  * - cursor?: Pagination cursor
45
52
  * - includeSubmodels?: Whether to fetch submodels for each shell (default: false)
46
53
  * - includeConceptDescriptions?: Whether to fetch concept descriptions (default: false)
47
54
  *
48
- * @returns Either `{ success: true; data: { shells, source, submodels? } }` or `{ success: false; error: ... }`.
55
+ * @returns Either
56
+ * `{ success: true; data: { shells, source, submodels?, warnings? } }`
57
+ * or `{ success: false; error: ... }`.
58
+ * When `strictRegistryResolution` is `true`, unresolved registry descriptors return
59
+ * `RegistryResolutionError` with `warnings`.
49
60
  */
50
61
  getAasList(options?: {
51
62
  preferRegistry?: boolean;
63
+ strictRegistryResolution?: boolean;
52
64
  limit?: number;
53
65
  cursor?: string;
54
66
  includeSubmodels?: boolean;
@@ -57,6 +69,7 @@ export declare class AasService {
57
69
  shells: AssetAdministrationShell[];
58
70
  source: 'registry' | 'repository';
59
71
  submodels?: Record<string, Submodel[]>;
72
+ warnings?: AasListResolutionWarning[];
60
73
  }, any>>;
61
74
  /**
62
75
  * Retrieves an Asset Administration Shell by ID.
@@ -71,7 +84,8 @@ export declare class AasService {
71
84
  * - includeSubmodels?: Whether to fetch submodels for the shell (default: false)
72
85
  * - includeConceptDescriptions?: Whether to fetch concept descriptions (default: false)
73
86
  *
74
- * @returns Either `{ success: true; data: { shell, descriptor?, submodels? } }` or `{ success: false; error: ... }`.
87
+ * @returns Either `{ success: true; data: { shell, descriptor?, submodels? }; etag? }` or `{ success: false; error: ... }`.
88
+ * `etag` is the entity tag of the shell, if the repository sends one.
75
89
  */
76
90
  getAasById(options: {
77
91
  aasIdentifier: string;
@@ -111,7 +125,8 @@ export declare class AasService {
111
125
  * - includeSubmodels?: Whether to fetch submodels for the shell (default: false)
112
126
  * - includeConceptDescriptions?: Whether to fetch concept descriptions (default: false)
113
127
  *
114
- * @returns Either `{ success: true; data: { shell, submodels? } }` or `{ success: false; error: ... }`.
128
+ * @returns Either `{ success: true; data: { shell, submodels? }; etag? }` or `{ success: false; error: ... }`.
129
+ * `etag` is the entity tag of the shell, if the repository sends one.
115
130
  */
116
131
  getAasByEndpoint(options: {
117
132
  endpoint: string;
@@ -151,12 +166,15 @@ export declare class AasService {
151
166
  * @param options Object containing:
152
167
  * - shell: The updated AAS
153
168
  * - updateInRegistry?: Whether to update the descriptor in the registry (default: true)
169
+ * - ifMatch?: Sent as `If-Match` header with the repository update; if the shell has changed, the update fails with
170
+ * `preconditionFailed` and the registry is not updated
154
171
  *
155
172
  * @returns Either `{ success: true; data: { shell, descriptor? } }` or `{ success: false; error: ... }`.
156
173
  */
157
174
  updateAas(options: {
158
175
  shell: AssetAdministrationShell;
159
176
  updateInRegistry?: boolean;
177
+ ifMatch?: string;
160
178
  }): Promise<ApiResult<{
161
179
  shell: AssetAdministrationShell;
162
180
  descriptor?: AssetAdministrationShellDescriptor;
@@ -165,18 +183,23 @@ export declare class AasService {
165
183
  * Deletes an Asset Administration Shell and optionally removes it from the registry.
166
184
  *
167
185
  * This method removes the descriptor from the registry first (if requested),
168
- * then deletes the AAS from the repository.
186
+ * then deletes the AAS from the repository. With `ifMatch`, the AAS is deleted from the repository first,
187
+ * so that a failed precondition leaves the descriptor in the registry.
169
188
  *
170
189
  * @param options Object containing:
171
190
  * - aasIdentifier: The AAS identifier to remove
172
191
  * - deleteFromRegistry?: Whether to delete from registry (default: true)
192
+ * - ifMatch?: Sent as `If-Match` header with the repository delete; if the shell has changed, the delete fails with
193
+ * `preconditionFailed`. Requires the repository configuration.
173
194
  *
174
195
  * @returns Either `{ success: true; data: void }` or `{ success: false; error: ... }`.
175
196
  */
176
197
  deleteAas(options: {
177
198
  aasIdentifier: string;
178
199
  deleteFromRegistry?: boolean;
200
+ ifMatch?: string;
179
201
  }): Promise<ApiResult<void, any>>;
202
+ private deleteAasFromRepository;
180
203
  /**
181
204
  * Retrieves Asset Administration Shells by their asset identifiers.
182
205
  *
@@ -220,6 +243,13 @@ export declare class AasService {
220
243
  submodelEndpoint?: string;
221
244
  submodelElementPath?: string;
222
245
  }, any>>;
246
+ /**
247
+ * Creates a repository configuration for an endpoint while preserving auth and middleware.
248
+ *
249
+ * @param basePath The endpoint base path to target
250
+ * @returns Configuration with endpoint basePath plus repository auth/settings
251
+ */
252
+ private createRepositoryEndpointConfiguration;
223
253
  /**
224
254
  * Helper method to create an AAS descriptor from an AssetAdministrationShell.
225
255
  * Populates descriptor fields from the shell including metadata and endpoint configuration.
@@ -4,6 +4,7 @@ import { AasRegistryClient } from '../clients/AasRegistryClient';
4
4
  import { AasRepositoryClient } from '../clients/AasRepositoryClient';
5
5
  import { Configuration } from '../generated';
6
6
  import { base64Decode, base64Encode } from '../lib/base64Url';
7
+ import { pickConditionalErrorFields } from '../lib/conditionalRequests';
7
8
  import { AssetAdministrationShellDescriptor } from '../models/Descriptors';
8
9
  import { extractEndpointHref } from '../utils/DescriptorUtils';
9
10
  import { SubmodelService } from './SubmodelService';
@@ -49,16 +50,23 @@ export class AasService {
49
50
  *
50
51
  * @param options Object containing:
51
52
  * - preferRegistry?: Whether to prefer registry over repository (default: true)
53
+ * - strictRegistryResolution?: Whether registry endpoint resolution failures should fail immediately (default: false)
52
54
  * - limit?: Maximum number of elements to retrieve
53
55
  * - cursor?: Pagination cursor
54
56
  * - includeSubmodels?: Whether to fetch submodels for each shell (default: false)
55
57
  * - includeConceptDescriptions?: Whether to fetch concept descriptions (default: false)
56
58
  *
57
- * @returns Either `{ success: true; data: { shells, source, submodels? } }` or `{ success: false; error: ... }`.
59
+ * @returns Either
60
+ * `{ success: true; data: { shells, source, submodels?, warnings? } }`
61
+ * or `{ success: false; error: ... }`.
62
+ * When `strictRegistryResolution` is `true`, unresolved registry descriptors return
63
+ * `RegistryResolutionError` with `warnings`.
58
64
  */
59
65
  async getAasList(options) {
60
66
  const preferRegistry = options?.preferRegistry ?? true;
67
+ const strictRegistryResolution = options?.strictRegistryResolution ?? false;
61
68
  const includeSubmodels = options?.includeSubmodels ?? false;
69
+ let registryResolutionWarnings = [];
62
70
  // Try registry first if configured and preferred
63
71
  if (preferRegistry && this.aasRegistryConfig) {
64
72
  const registryResult = await this.aasRegistryClient.getAllAssetAdministrationShellDescriptors({
@@ -69,34 +77,79 @@ export class AasService {
69
77
  if (registryResult.success) {
70
78
  // Fetch actual shells from descriptor endpoints
71
79
  const shells = [];
80
+ const warnings = [];
72
81
  for (const descriptor of registryResult.data.result) {
82
+ if (!descriptor.id) {
83
+ warnings.push({
84
+ errorType: 'MissingDescriptorId',
85
+ message: 'AAS descriptor does not contain an id and cannot be resolved',
86
+ });
87
+ continue;
88
+ }
73
89
  const endpoint = extractEndpointHref(descriptor, 'AAS-3.0');
74
- if (endpoint && descriptor.id) {
75
- // Extract base URL from endpoint (remove /shells/{id} part)
76
- const baseUrl = endpoint.match(/^(https?:\/\/[^/]+(?::\d+)?)/)?.[1] || endpoint;
77
- const config = new Configuration({ basePath: baseUrl });
78
- const shellResult = await this.aasRepositoryClient.getAssetAdministrationShellById({
79
- configuration: config,
80
- aasIdentifier: descriptor.id,
90
+ if (!endpoint) {
91
+ warnings.push({
92
+ descriptorId: descriptor.id,
93
+ errorType: 'MissingEndpoint',
94
+ message: 'AAS descriptor has no AAS-3.0 endpoint and cannot be resolved',
95
+ });
96
+ continue;
97
+ }
98
+ // Extract base URL from endpoint (remove /shells/{id} part)
99
+ const baseUrl = endpoint.match(/^(https?:\/\/[^/]+(?::\d+)?)/)?.[1] || endpoint;
100
+ const config = this.createRepositoryEndpointConfiguration(baseUrl);
101
+ const shellResult = await this.aasRepositoryClient.getAssetAdministrationShellById({
102
+ configuration: config,
103
+ aasIdentifier: descriptor.id,
104
+ });
105
+ if (shellResult.success) {
106
+ shells.push(shellResult.data);
107
+ }
108
+ else {
109
+ const resolutionError = shellResult.error;
110
+ warnings.push({
111
+ descriptorId: descriptor.id,
112
+ endpoint,
113
+ errorType: resolutionError?.errorType || 'EndpointResolutionError',
114
+ message: resolutionError?.message ||
115
+ resolutionError?.messages?.[0]?.text ||
116
+ 'Failed to resolve AAS from descriptor endpoint',
81
117
  });
82
- if (shellResult.success) {
83
- shells.push(shellResult.data);
84
- }
85
118
  }
86
119
  }
87
- // Fetch submodels if requested
88
- let submodelsMap;
89
- if (includeSubmodels) {
90
- submodelsMap = await this.fetchSubmodelsForShells(shells, options?.includeConceptDescriptions);
120
+ if (strictRegistryResolution && warnings.length > 0) {
121
+ return {
122
+ success: false,
123
+ error: {
124
+ errorType: 'RegistryResolutionError',
125
+ message: 'Failed to resolve one or more AAS descriptors via registry endpoints',
126
+ warnings,
127
+ },
128
+ };
91
129
  }
92
- return {
93
- success: true,
94
- data: {
95
- shells,
96
- source: 'registry',
97
- ...(submodelsMap && { submodels: submodelsMap }),
98
- },
99
- };
130
+ // If registry descriptors exist but none were resolvable, fall back to repository when possible.
131
+ if (warnings.length > 0 && shells.length === 0 && this.aasRepositoryConfig) {
132
+ registryResolutionWarnings = warnings;
133
+ }
134
+ else {
135
+ // Fetch submodels if requested
136
+ let submodelsMap;
137
+ if (includeSubmodels) {
138
+ submodelsMap = await this.fetchSubmodelsForShells(shells, options?.includeConceptDescriptions);
139
+ }
140
+ return {
141
+ success: true,
142
+ data: {
143
+ shells,
144
+ source: 'registry',
145
+ ...(submodelsMap && { submodels: submodelsMap }),
146
+ ...(warnings.length > 0 && { warnings }),
147
+ },
148
+ };
149
+ }
150
+ }
151
+ else {
152
+ registryResolutionWarnings = [];
100
153
  }
101
154
  }
102
155
  // Fall back to repository if registry failed or not configured
@@ -119,6 +172,7 @@ export class AasService {
119
172
  shells,
120
173
  source: 'repository',
121
174
  ...(submodelsMap && { submodels: submodelsMap }),
175
+ ...(registryResolutionWarnings.length > 0 && { warnings: registryResolutionWarnings }),
122
176
  },
123
177
  };
124
178
  }
@@ -145,7 +199,8 @@ export class AasService {
145
199
  * - includeSubmodels?: Whether to fetch submodels for the shell (default: false)
146
200
  * - includeConceptDescriptions?: Whether to fetch concept descriptions (default: false)
147
201
  *
148
- * @returns Either `{ success: true; data: { shell, descriptor?, submodels? } }` or `{ success: false; error: ... }`.
202
+ * @returns Either `{ success: true; data: { shell, descriptor?, submodels? }; etag? }` or `{ success: false; error: ... }`.
203
+ * `etag` is the entity tag of the shell, if the repository sends one.
149
204
  */
150
205
  async getAasById(options) {
151
206
  const { aasIdentifier, useRegistryEndpoint = true, includeSubmodels = false } = options;
@@ -162,7 +217,7 @@ export class AasService {
162
217
  // Extract base URL from endpoint (remove /shells/{id} part)
163
218
  const baseUrl = endpoint.match(/^(https?:\/\/[^/]+(?::\d+)?)/)?.[1] || endpoint;
164
219
  // Try to fetch from descriptor endpoint
165
- const config = new Configuration({ basePath: baseUrl });
220
+ const config = this.createRepositoryEndpointConfiguration(baseUrl);
166
221
  const shellResult = await this.aasRepositoryClient.getAssetAdministrationShellById({
167
222
  configuration: config,
168
223
  aasIdentifier,
@@ -182,6 +237,7 @@ export class AasService {
182
237
  descriptor,
183
238
  ...(submodels && { submodels }),
184
239
  },
240
+ etag: shellResult.etag,
185
241
  };
186
242
  }
187
243
  }
@@ -216,6 +272,7 @@ export class AasService {
216
272
  descriptor: undefined,
217
273
  ...(submodels && { submodels }),
218
274
  },
275
+ etag: shellResult.etag,
219
276
  };
220
277
  }
221
278
  return { success: false, error: shellResult.error };
@@ -274,7 +331,8 @@ export class AasService {
274
331
  * - includeSubmodels?: Whether to fetch submodels for the shell (default: false)
275
332
  * - includeConceptDescriptions?: Whether to fetch concept descriptions (default: false)
276
333
  *
277
- * @returns Either `{ success: true; data: { shell, submodels? } }` or `{ success: false; error: ... }`.
334
+ * @returns Either `{ success: true; data: { shell, submodels? }; etag? }` or `{ success: false; error: ... }`.
335
+ * `etag` is the entity tag of the shell, if the repository sends one.
278
336
  */
279
337
  async getAasByEndpoint(options) {
280
338
  const { endpoint, includeSubmodels = false } = options;
@@ -292,9 +350,21 @@ export class AasService {
292
350
  }
293
351
  const [, baseUrl, encodedId] = match;
294
352
  // Decode the ID
295
- const aasIdentifier = base64Decode(encodedId);
353
+ let aasIdentifier;
354
+ try {
355
+ aasIdentifier = base64Decode(encodedId);
356
+ }
357
+ catch {
358
+ return {
359
+ success: false,
360
+ error: {
361
+ errorType: 'InvalidEndpoint',
362
+ message: 'Endpoint contains an invalid Base64URL-encoded AAS identifier.',
363
+ },
364
+ };
365
+ }
296
366
  // Create configuration for the endpoint
297
- const config = new Configuration({ basePath: baseUrl });
367
+ const config = this.createRepositoryEndpointConfiguration(baseUrl);
298
368
  // Fetch the shell
299
369
  const shellResult = await this.aasRepositoryClient.getAssetAdministrationShellById({
300
370
  configuration: config,
@@ -316,6 +386,7 @@ export class AasService {
316
386
  shell,
317
387
  ...(submodels && { submodels }),
318
388
  },
389
+ etag: shellResult.etag,
319
390
  };
320
391
  }
321
392
  /**
@@ -388,11 +459,13 @@ export class AasService {
388
459
  * @param options Object containing:
389
460
  * - shell: The updated AAS
390
461
  * - updateInRegistry?: Whether to update the descriptor in the registry (default: true)
462
+ * - ifMatch?: Sent as `If-Match` header with the repository update; if the shell has changed, the update fails with
463
+ * `preconditionFailed` and the registry is not updated
391
464
  *
392
465
  * @returns Either `{ success: true; data: { shell, descriptor? } }` or `{ success: false; error: ... }`.
393
466
  */
394
467
  async updateAas(options) {
395
- const { shell, updateInRegistry = true } = options;
468
+ const { shell, updateInRegistry = true, ifMatch } = options;
396
469
  if (!this.aasRepositoryConfig) {
397
470
  return {
398
471
  success: false,
@@ -407,9 +480,10 @@ export class AasService {
407
480
  configuration: this.aasRepositoryConfig,
408
481
  aasIdentifier: shell.id,
409
482
  assetAdministrationShell: shell,
483
+ ifMatch,
410
484
  });
411
485
  if (!shellResult.success) {
412
- return { success: false, error: shellResult.error };
486
+ return { success: false, error: shellResult.error, ...pickConditionalErrorFields(shellResult) };
413
487
  }
414
488
  // Use the returned shell if available, otherwise use the input shell
415
489
  const updatedShell = shellResult.data || shell;
@@ -448,16 +522,35 @@ export class AasService {
448
522
  * Deletes an Asset Administration Shell and optionally removes it from the registry.
449
523
  *
450
524
  * This method removes the descriptor from the registry first (if requested),
451
- * then deletes the AAS from the repository.
525
+ * then deletes the AAS from the repository. With `ifMatch`, the AAS is deleted from the repository first,
526
+ * so that a failed precondition leaves the descriptor in the registry.
452
527
  *
453
528
  * @param options Object containing:
454
529
  * - aasIdentifier: The AAS identifier to remove
455
530
  * - deleteFromRegistry?: Whether to delete from registry (default: true)
531
+ * - ifMatch?: Sent as `If-Match` header with the repository delete; if the shell has changed, the delete fails with
532
+ * `preconditionFailed`. Requires the repository configuration.
456
533
  *
457
534
  * @returns Either `{ success: true; data: void }` or `{ success: false; error: ... }`.
458
535
  */
459
536
  async deleteAas(options) {
460
- const { aasIdentifier, deleteFromRegistry = true } = options;
537
+ const { aasIdentifier, deleteFromRegistry = true, ifMatch } = options;
538
+ // A conditional delete must not remove the descriptor if the precondition fails or cannot be checked
539
+ if (ifMatch) {
540
+ if (!this.aasRepositoryConfig) {
541
+ return {
542
+ success: false,
543
+ error: {
544
+ errorType: 'ConfigurationError',
545
+ message: 'Repository configuration required for a conditional delete',
546
+ },
547
+ };
548
+ }
549
+ const repoResult = await this.deleteAasFromRepository(aasIdentifier, ifMatch);
550
+ if (!repoResult.success) {
551
+ return repoResult;
552
+ }
553
+ }
461
554
  // Remove from registry first if configured and requested
462
555
  if (deleteFromRegistry && this.aasRegistryConfig) {
463
556
  const registryResult = await this.aasRegistryClient.deleteAssetAdministrationShellDescriptorById({
@@ -469,13 +562,23 @@ export class AasService {
469
562
  }
470
563
  }
471
564
  // Remove from repository
565
+ if (!ifMatch) {
566
+ const repoResult = await this.deleteAasFromRepository(aasIdentifier);
567
+ if (!repoResult.success) {
568
+ return repoResult;
569
+ }
570
+ }
571
+ return { success: true, data: undefined };
572
+ }
573
+ async deleteAasFromRepository(aasIdentifier, ifMatch) {
472
574
  if (this.aasRepositoryConfig) {
473
575
  const repoResult = await this.aasRepositoryClient.deleteAssetAdministrationShellById({
474
576
  configuration: this.aasRepositoryConfig,
475
577
  aasIdentifier,
578
+ ifMatch,
476
579
  });
477
580
  if (!repoResult.success) {
478
- return { success: false, error: repoResult.error };
581
+ return { success: false, error: repoResult.error, ...pickConditionalErrorFields(repoResult) };
479
582
  }
480
583
  }
481
584
  return { success: true, data: undefined };
@@ -660,6 +763,29 @@ export class AasService {
660
763
  },
661
764
  };
662
765
  }
766
+ /**
767
+ * Creates a repository configuration for an endpoint while preserving auth and middleware.
768
+ *
769
+ * @param basePath The endpoint base path to target
770
+ * @returns Configuration with endpoint basePath plus repository auth/settings
771
+ */
772
+ createRepositoryEndpointConfiguration(basePath) {
773
+ if (!this.aasRepositoryConfig) {
774
+ return new Configuration({ basePath });
775
+ }
776
+ return new Configuration({
777
+ basePath,
778
+ fetchApi: this.aasRepositoryConfig.fetchApi,
779
+ middleware: this.aasRepositoryConfig.middleware,
780
+ queryParamsStringify: this.aasRepositoryConfig.queryParamsStringify,
781
+ username: this.aasRepositoryConfig.username,
782
+ password: this.aasRepositoryConfig.password,
783
+ apiKey: this.aasRepositoryConfig.apiKey,
784
+ accessToken: this.aasRepositoryConfig.accessToken,
785
+ headers: this.aasRepositoryConfig.headers,
786
+ credentials: this.aasRepositoryConfig.credentials,
787
+ });
788
+ }
663
789
  /**
664
790
  * Helper method to create an AAS descriptor from an AssetAdministrationShell.
665
791
  * Populates descriptor fields from the shell including metadata and endpoint configuration.