basyx-typescript-sdk 2.2.5 → 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.
@@ -1 +1,2 @@
1
- export declare function applyDefaults(configuration: any): any;
1
+ import type { ConditionalRequestHeaders } from '../models/api';
2
+ export declare function applyDefaults(configuration: any, conditionalHeaders?: ConditionalRequestHeaders): any;
@@ -1,4 +1,4 @@
1
- export function applyDefaults(configuration) {
1
+ export function applyDefaults(configuration, conditionalHeaders) {
2
2
  // Extract configuration properties
3
3
  const options = {
4
4
  basePath: configuration.basePath || undefined,
@@ -9,7 +9,7 @@ export function applyDefaults(configuration) {
9
9
  password: configuration.password || undefined,
10
10
  apiKey: configuration.apiKey || undefined,
11
11
  accessToken: configuration.accessToken || undefined,
12
- headers: configuration.headers || undefined,
12
+ headers: withConditionalHeaders(configuration.headers || undefined, conditionalHeaders),
13
13
  credentials: configuration.credentials || undefined,
14
14
  };
15
15
  // Create a new configuration instance with defaults applied
@@ -20,3 +20,28 @@ function getDefaultFetchApi() {
20
20
  // In Node (>=18) or browser, global fetch is available.
21
21
  return fetch.bind(globalThis);
22
22
  }
23
+ /**
24
+ * Adds `If-Match` and `If-None-Match` to the configured headers. A passed condition replaces a configured header of
25
+ * the same name regardless of its case; without conditions the configured headers are returned unchanged.
26
+ */
27
+ function withConditionalHeaders(headers, conditionalHeaders) {
28
+ const conditions = {
29
+ 'If-Match': conditionalHeaders?.ifMatch,
30
+ 'If-None-Match': conditionalHeaders?.ifNoneMatch,
31
+ };
32
+ const names = Object.keys(conditions).filter((name) => conditions[name]);
33
+ if (names.length === 0) {
34
+ return headers;
35
+ }
36
+ const lowerCaseNames = names.map((name) => name.toLowerCase());
37
+ const merged = {};
38
+ for (const [name, value] of Object.entries(headers ?? {})) {
39
+ if (!lowerCaseNames.includes(name.toLowerCase())) {
40
+ merged[name] = value;
41
+ }
42
+ }
43
+ for (const name of names) {
44
+ merged[name] = conditions[name];
45
+ }
46
+ return merged;
47
+ }
@@ -0,0 +1,28 @@
1
+ import type { ApiResult, NotModifiedResult } from '../models/api';
2
+ type ConditionalErrorFields = {
3
+ etag?: string;
4
+ preconditionFailed?: boolean;
5
+ preconditionRequired?: boolean;
6
+ };
7
+ /**
8
+ * Returns the `ETag` header of a response, or `undefined` if the server sent none.
9
+ * The entity tag is opaque and returned unchanged.
10
+ */
11
+ export declare function getEtag(response: unknown): string | undefined;
12
+ /**
13
+ * Returns the conditional request fields of a failed request: the `ETag` of the error response and the flags for
14
+ * `412 Precondition Failed` and `428 Precondition Required`. Fields that do not apply are omitted.
15
+ */
16
+ export declare function getConditionalErrorFields(err: unknown): ConditionalErrorFields;
17
+ /**
18
+ * Returns the conditional request fields of a failed {@link ApiResult}, so that a composite operation can pass them on.
19
+ */
20
+ export declare function pickConditionalErrorFields(result: Extract<ApiResult<unknown, unknown>, {
21
+ success: false;
22
+ }>): ConditionalErrorFields;
23
+ /**
24
+ * Returns the {@link NotModifiedResult} for a `304 Not Modified` answer to a read with `ifNoneMatch`, or `undefined`
25
+ * for any other error.
26
+ */
27
+ export declare function getNotModifiedResult<IfNoneMatch extends string | undefined>(err: unknown, ifNoneMatch: IfNoneMatch | undefined): (IfNoneMatch extends undefined ? never : NotModifiedResult) | undefined;
28
+ export {};
@@ -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,14 +1,50 @@
1
1
  /**
2
2
  * A union for "no-throw" style responses:
3
- * Success => { success: true; data: T; statusCode?: number }
4
- * Failure => { success: false; error: E; statusCode?: number }
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;
9
13
  statusCode?: number;
14
+ etag?: string;
15
+ notModified?: false;
10
16
  } | {
11
17
  success: false;
12
18
  error: E;
13
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;
14
50
  };
@@ -84,7 +84,8 @@ export declare class AasService {
84
84
  * - includeSubmodels?: Whether to fetch submodels for the shell (default: false)
85
85
  * - includeConceptDescriptions?: Whether to fetch concept descriptions (default: false)
86
86
  *
87
- * @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.
88
89
  */
89
90
  getAasById(options: {
90
91
  aasIdentifier: string;
@@ -124,7 +125,8 @@ export declare class AasService {
124
125
  * - includeSubmodels?: Whether to fetch submodels for the shell (default: false)
125
126
  * - includeConceptDescriptions?: Whether to fetch concept descriptions (default: false)
126
127
  *
127
- * @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.
128
130
  */
129
131
  getAasByEndpoint(options: {
130
132
  endpoint: string;
@@ -164,12 +166,15 @@ export declare class AasService {
164
166
  * @param options Object containing:
165
167
  * - shell: The updated AAS
166
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
167
171
  *
168
172
  * @returns Either `{ success: true; data: { shell, descriptor? } }` or `{ success: false; error: ... }`.
169
173
  */
170
174
  updateAas(options: {
171
175
  shell: AssetAdministrationShell;
172
176
  updateInRegistry?: boolean;
177
+ ifMatch?: string;
173
178
  }): Promise<ApiResult<{
174
179
  shell: AssetAdministrationShell;
175
180
  descriptor?: AssetAdministrationShellDescriptor;
@@ -178,18 +183,23 @@ export declare class AasService {
178
183
  * Deletes an Asset Administration Shell and optionally removes it from the registry.
179
184
  *
180
185
  * This method removes the descriptor from the registry first (if requested),
181
- * 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.
182
188
  *
183
189
  * @param options Object containing:
184
190
  * - aasIdentifier: The AAS identifier to remove
185
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.
186
194
  *
187
195
  * @returns Either `{ success: true; data: void }` or `{ success: false; error: ... }`.
188
196
  */
189
197
  deleteAas(options: {
190
198
  aasIdentifier: string;
191
199
  deleteFromRegistry?: boolean;
200
+ ifMatch?: string;
192
201
  }): Promise<ApiResult<void, any>>;
202
+ private deleteAasFromRepository;
193
203
  /**
194
204
  * Retrieves Asset Administration Shells by their asset identifiers.
195
205
  *
@@ -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';
@@ -198,7 +199,8 @@ export class AasService {
198
199
  * - includeSubmodels?: Whether to fetch submodels for the shell (default: false)
199
200
  * - includeConceptDescriptions?: Whether to fetch concept descriptions (default: false)
200
201
  *
201
- * @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.
202
204
  */
203
205
  async getAasById(options) {
204
206
  const { aasIdentifier, useRegistryEndpoint = true, includeSubmodels = false } = options;
@@ -235,6 +237,7 @@ export class AasService {
235
237
  descriptor,
236
238
  ...(submodels && { submodels }),
237
239
  },
240
+ etag: shellResult.etag,
238
241
  };
239
242
  }
240
243
  }
@@ -269,6 +272,7 @@ export class AasService {
269
272
  descriptor: undefined,
270
273
  ...(submodels && { submodels }),
271
274
  },
275
+ etag: shellResult.etag,
272
276
  };
273
277
  }
274
278
  return { success: false, error: shellResult.error };
@@ -327,7 +331,8 @@ export class AasService {
327
331
  * - includeSubmodels?: Whether to fetch submodels for the shell (default: false)
328
332
  * - includeConceptDescriptions?: Whether to fetch concept descriptions (default: false)
329
333
  *
330
- * @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.
331
336
  */
332
337
  async getAasByEndpoint(options) {
333
338
  const { endpoint, includeSubmodels = false } = options;
@@ -381,6 +386,7 @@ export class AasService {
381
386
  shell,
382
387
  ...(submodels && { submodels }),
383
388
  },
389
+ etag: shellResult.etag,
384
390
  };
385
391
  }
386
392
  /**
@@ -453,11 +459,13 @@ export class AasService {
453
459
  * @param options Object containing:
454
460
  * - shell: The updated AAS
455
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
456
464
  *
457
465
  * @returns Either `{ success: true; data: { shell, descriptor? } }` or `{ success: false; error: ... }`.
458
466
  */
459
467
  async updateAas(options) {
460
- const { shell, updateInRegistry = true } = options;
468
+ const { shell, updateInRegistry = true, ifMatch } = options;
461
469
  if (!this.aasRepositoryConfig) {
462
470
  return {
463
471
  success: false,
@@ -472,9 +480,10 @@ export class AasService {
472
480
  configuration: this.aasRepositoryConfig,
473
481
  aasIdentifier: shell.id,
474
482
  assetAdministrationShell: shell,
483
+ ifMatch,
475
484
  });
476
485
  if (!shellResult.success) {
477
- return { success: false, error: shellResult.error };
486
+ return { success: false, error: shellResult.error, ...pickConditionalErrorFields(shellResult) };
478
487
  }
479
488
  // Use the returned shell if available, otherwise use the input shell
480
489
  const updatedShell = shellResult.data || shell;
@@ -513,16 +522,35 @@ export class AasService {
513
522
  * Deletes an Asset Administration Shell and optionally removes it from the registry.
514
523
  *
515
524
  * This method removes the descriptor from the registry first (if requested),
516
- * 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.
517
527
  *
518
528
  * @param options Object containing:
519
529
  * - aasIdentifier: The AAS identifier to remove
520
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.
521
533
  *
522
534
  * @returns Either `{ success: true; data: void }` or `{ success: false; error: ... }`.
523
535
  */
524
536
  async deleteAas(options) {
525
- 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
+ }
526
554
  // Remove from registry first if configured and requested
527
555
  if (deleteFromRegistry && this.aasRegistryConfig) {
528
556
  const registryResult = await this.aasRegistryClient.deleteAssetAdministrationShellDescriptorById({
@@ -534,13 +562,23 @@ export class AasService {
534
562
  }
535
563
  }
536
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) {
537
574
  if (this.aasRepositoryConfig) {
538
575
  const repoResult = await this.aasRepositoryClient.deleteAssetAdministrationShellById({
539
576
  configuration: this.aasRepositoryConfig,
540
577
  aasIdentifier,
578
+ ifMatch,
541
579
  });
542
580
  if (!repoResult.success) {
543
- return { success: false, error: repoResult.error };
581
+ return { success: false, error: repoResult.error, ...pickConditionalErrorFields(repoResult) };
544
582
  }
545
583
  }
546
584
  return { success: true, data: undefined };
@@ -74,7 +74,8 @@ export declare class SubmodelService {
74
74
  * - useRegistryEndpoint?: Whether to try registry endpoint first (default: true)
75
75
  * - includeConceptDescriptions?: Whether to fetch concept descriptions (default: false)
76
76
  *
77
- * @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.
78
79
  */
79
80
  getSubmodelById(options: {
80
81
  submodelIdentifier: string;
@@ -112,7 +113,8 @@ export declare class SubmodelService {
112
113
  * - endpoint: The endpoint URL (format: http://host/submodels/{base64EncodedId})
113
114
  * - includeConceptDescriptions?: Whether to fetch concept descriptions (default: false)
114
115
  *
115
- * @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.
116
118
  */
117
119
  getSubmodelByEndpoint(options: {
118
120
  endpoint: string;
@@ -158,12 +160,15 @@ export declare class SubmodelService {
158
160
  * @param options Object containing:
159
161
  * - submodel: The updated Submodel
160
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
161
165
  *
162
166
  * @returns Either `{ success: true; data: { submodel, descriptor? } }` or `{ success: false; error: ... }`.
163
167
  */
164
168
  updateSubmodel(options: {
165
169
  submodel: Submodel;
166
170
  updateInRegistry?: boolean;
171
+ ifMatch?: string;
167
172
  }): Promise<ApiResult<{
168
173
  submodel: Submodel;
169
174
  descriptor?: SubmodelDescriptor;
@@ -172,18 +177,23 @@ export declare class SubmodelService {
172
177
  * Deletes a Submodel and optionally removes it from the registry.
173
178
  *
174
179
  * This method removes the descriptor from the registry first (if requested),
175
- * 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.
176
182
  *
177
183
  * @param options Object containing:
178
184
  * - submodelIdentifier: The Submodel identifier to remove
179
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.
180
188
  *
181
189
  * @returns Either `{ success: true; data: void }` or `{ success: false; error: ... }`.
182
190
  */
183
191
  deleteSubmodel(options: {
184
192
  submodelIdentifier: string;
185
193
  deleteFromRegistry?: boolean;
194
+ ifMatch?: string;
186
195
  }): Promise<ApiResult<void, any>>;
196
+ private deleteSubmodelFromRepository;
187
197
  /**
188
198
  * Helper method to create a Submodel descriptor from a Submodel.
189
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
@@ -189,7 +190,8 @@ export class SubmodelService {
189
190
  * - useRegistryEndpoint?: Whether to try registry endpoint first (default: true)
190
191
  * - includeConceptDescriptions?: Whether to fetch concept descriptions (default: false)
191
192
  *
192
- * @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.
193
195
  */
194
196
  async getSubmodelById(options) {
195
197
  const { submodelIdentifier, useRegistryEndpoint = true, includeConceptDescriptions = false } = options;
@@ -217,6 +219,7 @@ export class SubmodelService {
217
219
  conceptDescriptions: submodelResult.data.conceptDescriptions,
218
220
  }),
219
221
  },
222
+ etag: submodelResult.etag,
220
223
  };
221
224
  }
222
225
  }
@@ -251,6 +254,7 @@ export class SubmodelService {
251
254
  descriptor: undefined,
252
255
  ...(conceptDescriptions && { conceptDescriptions }),
253
256
  },
257
+ etag: submodelResult.etag,
254
258
  };
255
259
  }
256
260
  return { success: false, error: submodelResult.error };
@@ -308,7 +312,8 @@ export class SubmodelService {
308
312
  * - endpoint: The endpoint URL (format: http://host/submodels/{base64EncodedId})
309
313
  * - includeConceptDescriptions?: Whether to fetch concept descriptions (default: false)
310
314
  *
311
- * @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.
312
317
  */
313
318
  async getSubmodelByEndpoint(options) {
314
319
  const { endpoint, includeConceptDescriptions = false } = options;
@@ -361,6 +366,7 @@ export class SubmodelService {
361
366
  submodel,
362
367
  ...(conceptDescriptions && { conceptDescriptions }),
363
368
  },
369
+ etag: submodelResult.etag,
364
370
  };
365
371
  }
366
372
  /**
@@ -456,11 +462,13 @@ export class SubmodelService {
456
462
  * @param options Object containing:
457
463
  * - submodel: The updated Submodel
458
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
459
467
  *
460
468
  * @returns Either `{ success: true; data: { submodel, descriptor? } }` or `{ success: false; error: ... }`.
461
469
  */
462
470
  async updateSubmodel(options) {
463
- const { submodel, updateInRegistry = true } = options;
471
+ const { submodel, updateInRegistry = true, ifMatch } = options;
464
472
  if (!this.submodelRepositoryConfig) {
465
473
  return {
466
474
  success: false,
@@ -475,9 +483,10 @@ export class SubmodelService {
475
483
  configuration: this.submodelRepositoryConfig,
476
484
  submodelIdentifier: submodel.id,
477
485
  submodel: submodel,
486
+ ifMatch,
478
487
  });
479
488
  if (!submodelResult.success) {
480
- return { success: false, error: submodelResult.error };
489
+ return { success: false, error: submodelResult.error, ...pickConditionalErrorFields(submodelResult) };
481
490
  }
482
491
  // Use the returned submodel if available, otherwise use the input submodel
483
492
  const updatedSubmodel = submodelResult.data || submodel;
@@ -514,16 +523,35 @@ export class SubmodelService {
514
523
  * Deletes a Submodel and optionally removes it from the registry.
515
524
  *
516
525
  * This method removes the descriptor from the registry first (if requested),
517
- * 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.
518
528
  *
519
529
  * @param options Object containing:
520
530
  * - submodelIdentifier: The Submodel identifier to remove
521
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.
522
534
  *
523
535
  * @returns Either `{ success: true; data: void }` or `{ success: false; error: ... }`.
524
536
  */
525
537
  async deleteSubmodel(options) {
526
- 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
+ }
527
555
  // Remove from registry first if configured and requested
528
556
  if (deleteFromRegistry && this.submodelRegistryConfig) {
529
557
  const registryResult = await this.submodelRegistryClient.deleteSubmodelDescriptorById({
@@ -535,13 +563,27 @@ export class SubmodelService {
535
563
  }
536
564
  }
537
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) {
538
575
  if (this.submodelRepositoryConfig) {
539
576
  const repositoryResult = await this.submodelRepositoryClient.deleteSubmodelById({
540
577
  configuration: this.submodelRepositoryConfig,
541
578
  submodelIdentifier,
579
+ ifMatch,
542
580
  });
543
581
  if (!repositoryResult.success) {
544
- return { success: false, error: repositoryResult.error };
582
+ return {
583
+ success: false,
584
+ error: repositoryResult.error,
585
+ ...pickConditionalErrorFields(repositoryResult),
586
+ };
545
587
  }
546
588
  }
547
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.5",
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",