basyx-typescript-sdk 2.3.1 → 2.4.1

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 (64) hide show
  1. package/README.md +68 -1
  2. package/bundle/index.cjs +1463 -105
  3. package/bundle/index.cjs.map +1 -1
  4. package/bundle/index.mjs +1395 -106
  5. package/bundle/index.mjs.map +1 -1
  6. package/dist/clients/AasRegistryClient.d.ts +20 -0
  7. package/dist/clients/AasRegistryClient.js +40 -0
  8. package/dist/clients/AasRepositoryClient.d.ts +31 -3
  9. package/dist/clients/AasRepositoryClient.js +61 -4
  10. package/dist/clients/ConceptDescriptionRepositoryClient.d.ts +20 -0
  11. package/dist/clients/ConceptDescriptionRepositoryClient.js +40 -0
  12. package/dist/clients/SubmodelRegistryClient.d.ts +20 -0
  13. package/dist/clients/SubmodelRegistryClient.js +40 -0
  14. package/dist/clients/SubmodelRepositoryClient.d.ts +33 -7
  15. package/dist/clients/SubmodelRepositoryClient.js +61 -12
  16. package/dist/generated/AasRegistryService/apis/AssetAdministrationShellRegistryAPIApi.d.ts +14 -1
  17. package/dist/generated/AasRegistryService/apis/AssetAdministrationShellRegistryAPIApi.js +29 -0
  18. package/dist/generated/AasRegistryService/models/index.d.ts +374 -0
  19. package/dist/generated/AasRegistryService/models/index.js +6 -0
  20. package/dist/generated/AasRepositoryService/apis/AssetAdministrationShellRepositoryAPIApi.d.ts +14 -1
  21. package/dist/generated/AasRepositoryService/apis/AssetAdministrationShellRepositoryAPIApi.js +29 -0
  22. package/dist/generated/AasRepositoryService/models/index.d.ts +381 -0
  23. package/dist/generated/AasRepositoryService/models/index.js +7 -0
  24. package/dist/generated/ConceptDescriptionRepositoryService/apis/ConceptDescriptionRepositoryAPIApi.d.ts +14 -1
  25. package/dist/generated/ConceptDescriptionRepositoryService/apis/ConceptDescriptionRepositoryAPIApi.js +29 -0
  26. package/dist/generated/ConceptDescriptionRepositoryService/models/index.d.ts +381 -0
  27. package/dist/generated/ConceptDescriptionRepositoryService/models/index.js +7 -0
  28. package/dist/generated/SubmodelRegistryService/apis/SubmodelRegistryAPIApi.d.ts +14 -1
  29. package/dist/generated/SubmodelRegistryService/apis/SubmodelRegistryAPIApi.js +29 -0
  30. package/dist/generated/SubmodelRegistryService/models/index.d.ts +381 -0
  31. package/dist/generated/SubmodelRegistryService/models/index.js +7 -0
  32. package/dist/generated/SubmodelRepositoryService/apis/SubmodelRepositoryAPIApi.d.ts +14 -3
  33. package/dist/generated/SubmodelRepositoryService/apis/SubmodelRepositoryAPIApi.js +31 -8
  34. package/dist/generated/SubmodelRepositoryService/models/index.d.ts +381 -0
  35. package/dist/generated/SubmodelRepositoryService/models/index.js +7 -0
  36. package/dist/lib/endpointConfiguration.d.ts +71 -0
  37. package/dist/lib/endpointConfiguration.js +101 -0
  38. package/dist/lib/index.d.ts +1 -0
  39. package/dist/lib/index.js +2 -0
  40. package/dist/lib/operationHandle.d.ts +10 -0
  41. package/dist/lib/operationHandle.js +26 -0
  42. package/dist/lib/queryJsonization.d.ts +17 -0
  43. package/dist/lib/queryJsonization.js +309 -0
  44. package/dist/lib/queryRequests.d.ts +24 -0
  45. package/dist/lib/queryRequests.js +44 -0
  46. package/dist/models/Query.d.ts +378 -0
  47. package/dist/models/Query.js +430 -0
  48. package/dist/models/QueryResult.d.ts +22 -0
  49. package/dist/models/QueryResult.js +1 -0
  50. package/dist/models/api.d.ts +10 -0
  51. package/dist/models/index.d.ts +2 -0
  52. package/dist/models/index.js +2 -0
  53. package/dist/services/AasService.d.ts +15 -4
  54. package/dist/services/AasService.js +38 -40
  55. package/dist/services/SubmodelService.d.ts +9 -8
  56. package/dist/services/SubmodelService.js +17 -34
  57. package/dist/services/index.d.ts +1 -0
  58. package/dist/utils/DescriptorUtils.d.ts +27 -1
  59. package/dist/utils/DescriptorUtils.js +65 -27
  60. package/dist/utils/ServiceDescriptionUtils.d.ts +30 -0
  61. package/dist/utils/ServiceDescriptionUtils.js +43 -0
  62. package/dist/utils/index.d.ts +2 -0
  63. package/dist/utils/index.js +2 -0
  64. package/package.json +1 -1
@@ -2,11 +2,10 @@ import { KeyTypes, ReferenceTypes, } from '@aas-core-works/aas-core3.1-typescrip
2
2
  import { AasDiscoveryClient } from '../clients/AasDiscoveryClient';
3
3
  import { AasRegistryClient } from '../clients/AasRegistryClient';
4
4
  import { AasRepositoryClient } from '../clients/AasRepositoryClient';
5
- import { Configuration } from '../generated';
6
5
  import { base64Decode, base64Encode } from '../lib/base64Url';
7
6
  import { pickConditionalErrorFields } from '../lib/conditionalRequests';
7
+ import { createEndpointConfiguration, resolveDescriptorEndpoint, splitResourceHref, } from '../lib/endpointConfiguration';
8
8
  import { AssetAdministrationShellDescriptor } from '../models/Descriptors';
9
- import { extractEndpointHref } from '../utils/DescriptorUtils';
10
9
  import { SubmodelService } from './SubmodelService';
11
10
  /**
12
11
  * AasService combines and orchestrates multiple clients and services, including:
@@ -25,6 +24,7 @@ export class AasService {
25
24
  aasRegistryConfig;
26
25
  aasRepositoryConfig;
27
26
  discoveryConfig;
27
+ endpointConfiguration;
28
28
  submodelService;
29
29
  constructor(config) {
30
30
  this.aasRegistryClient = new AasRegistryClient();
@@ -33,11 +33,13 @@ export class AasService {
33
33
  this.aasRegistryConfig = config.aasRegistryConfig;
34
34
  this.aasRepositoryConfig = config.aasRepositoryConfig;
35
35
  this.discoveryConfig = config.discoveryConfig;
36
+ this.endpointConfiguration = config.endpointConfiguration;
36
37
  // Use separate submodel configs if provided, otherwise fall back to AAS configs
37
38
  this.submodelService = new SubmodelService({
38
39
  submodelRegistryConfig: config.submodelRegistryConfig ?? config.aasRegistryConfig,
39
40
  submodelRepositoryConfig: config.submodelRepositoryConfig ?? config.aasRepositoryConfig,
40
41
  conceptDescriptionRepositoryConfig: config.conceptDescriptionRepositoryConfig,
42
+ endpointConfiguration: config.endpointConfiguration,
41
43
  });
42
44
  }
43
45
  /**
@@ -86,20 +88,23 @@ export class AasService {
86
88
  });
87
89
  continue;
88
90
  }
89
- const endpoint = extractEndpointHref(descriptor, 'AAS-3.0');
90
- if (!endpoint) {
91
+ const resolvedEndpoint = resolveDescriptorEndpoint(descriptor, 'AAS');
92
+ if (!resolvedEndpoint) {
91
93
  warnings.push({
92
94
  descriptorId: descriptor.id,
93
95
  errorType: 'MissingEndpoint',
94
- message: 'AAS descriptor has no AAS-3.0 endpoint and cannot be resolved',
96
+ message: 'AAS descriptor has no AAS-3.x endpoint and cannot be resolved',
95
97
  });
96
98
  continue;
97
99
  }
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);
100
+ const endpoint = resolvedEndpoint.href;
101
+ const configResult = await this.createEndpointConfiguration(endpoint, resolvedEndpoint.basePath);
102
+ if (!configResult.success) {
103
+ warnings.push({ descriptorId: descriptor.id, endpoint, ...configResult.error });
104
+ continue;
105
+ }
101
106
  const shellResult = await this.aasRepositoryClient.getAssetAdministrationShellById({
102
- configuration: config,
107
+ configuration: configResult.configuration,
103
108
  aasIdentifier: descriptor.id,
104
109
  });
105
110
  if (shellResult.success) {
@@ -212,14 +217,15 @@ export class AasService {
212
217
  });
213
218
  if (descriptorResult.success) {
214
219
  const descriptor = descriptorResult.data;
215
- const endpoint = extractEndpointHref(descriptor, 'AAS-3.0');
216
- if (endpoint) {
217
- // Extract base URL from endpoint (remove /shells/{id} part)
218
- const baseUrl = endpoint.match(/^(https?:\/\/[^/]+(?::\d+)?)/)?.[1] || endpoint;
220
+ const resolvedEndpoint = resolveDescriptorEndpoint(descriptor, 'AAS');
221
+ const configResult = resolvedEndpoint
222
+ ? await this.createEndpointConfiguration(resolvedEndpoint.href, resolvedEndpoint.basePath)
223
+ : undefined;
224
+ // A rejected endpoint is not contacted; fall through to the repository
225
+ if (configResult?.success) {
219
226
  // Try to fetch from descriptor endpoint
220
- const config = this.createRepositoryEndpointConfiguration(baseUrl);
221
227
  const shellResult = await this.aasRepositoryClient.getAssetAdministrationShellById({
222
- configuration: config,
228
+ configuration: configResult.configuration,
223
229
  aasIdentifier,
224
230
  });
225
231
  if (shellResult.success) {
@@ -299,7 +305,7 @@ export class AasService {
299
305
  aasIdentifier,
300
306
  });
301
307
  if (descriptorResult.success) {
302
- const endpoint = extractEndpointHref(descriptorResult.data, 'AAS-3.0');
308
+ const endpoint = resolveDescriptorEndpoint(descriptorResult.data, 'AAS')?.href;
303
309
  if (endpoint) {
304
310
  return { success: true, data: endpoint };
305
311
  }
@@ -325,9 +331,10 @@ export class AasService {
325
331
  *
326
332
  * Extracts the base URL and base64url-encoded AAS identifier from the endpoint,
327
333
  * decodes the identifier, and fetches the shell from the repository.
334
+ * If an `endpointConfiguration` hook is configured, it decides whether and how the endpoint is contacted.
328
335
  *
329
336
  * @param options Object containing:
330
- * - endpoint: The endpoint URL (format: http://host/shells/{base64EncodedId})
337
+ * - endpoint: The endpoint URL (format: http://host[/basePath]/shells/{base64EncodedId})
331
338
  * - includeSubmodels?: Whether to fetch submodels for the shell (default: false)
332
339
  * - includeConceptDescriptions?: Whether to fetch concept descriptions (default: false)
333
340
  *
@@ -338,8 +345,8 @@ export class AasService {
338
345
  const { endpoint, includeSubmodels = false } = options;
339
346
  // Extract base URL and encoded ID from endpoint
340
347
  // Expected format: http://localhost:8081/shells/base64EncodedId
341
- const match = endpoint.match(/^(https?:\/\/[^/]+(?::\d+)?)\/shells\/([^/]+)$/);
342
- if (!match) {
348
+ const parts = splitResourceHref(endpoint, 'shells');
349
+ if (!parts) {
343
350
  return {
344
351
  success: false,
345
352
  error: {
@@ -348,7 +355,7 @@ export class AasService {
348
355
  },
349
356
  };
350
357
  }
351
- const [, baseUrl, encodedId] = match;
358
+ const { basePath: baseUrl, encodedId } = parts;
352
359
  // Decode the ID
353
360
  let aasIdentifier;
354
361
  try {
@@ -364,10 +371,13 @@ export class AasService {
364
371
  };
365
372
  }
366
373
  // Create configuration for the endpoint
367
- const config = this.createRepositoryEndpointConfiguration(baseUrl);
374
+ const configResult = await this.createEndpointConfiguration(endpoint, baseUrl);
375
+ if (!configResult.success) {
376
+ return { success: false, error: configResult.error };
377
+ }
368
378
  // Fetch the shell
369
379
  const shellResult = await this.aasRepositoryClient.getAssetAdministrationShellById({
370
- configuration: config,
380
+ configuration: configResult.configuration,
371
381
  aasIdentifier,
372
382
  });
373
383
  if (!shellResult.success) {
@@ -764,27 +774,15 @@ export class AasService {
764
774
  };
765
775
  }
766
776
  /**
767
- * Creates a repository configuration for an endpoint while preserving auth and middleware.
777
+ * Determines the configuration for a request to an AAS endpoint, using the `endpointConfiguration` hook if
778
+ * configured and the repository settings otherwise.
768
779
  *
780
+ * @param href The full endpoint URL
769
781
  * @param basePath The endpoint base path to target
770
- * @returns Configuration with endpoint basePath plus repository auth/settings
782
+ * @returns The configuration, or an `EndpointRejected` error
771
783
  */
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
- });
784
+ createEndpointConfiguration(href, basePath) {
785
+ return createEndpointConfiguration(href, basePath, this.endpointConfiguration, this.aasRepositoryConfig);
788
786
  }
789
787
  /**
790
788
  * Helper method to create an AAS descriptor from an AssetAdministrationShell.
@@ -1,11 +1,17 @@
1
1
  import type { ConceptDescription, Submodel } from '@aas-core-works/aas-core3.1-typescript/types';
2
2
  import type { ApiResult } from '../models/api';
3
3
  import { Configuration } from '../generated/runtime';
4
+ import { type EndpointConfigurationResolver } from '../lib/endpointConfiguration';
4
5
  import { SubmodelDescriptor } from '../models/Descriptors';
5
6
  export interface SubmodelServiceConfig {
6
7
  submodelRegistryConfig?: Configuration;
7
8
  submodelRepositoryConfig?: Configuration;
8
9
  conceptDescriptionRepositoryConfig?: Configuration;
10
+ /**
11
+ * Returns the configuration for requests to a descriptor endpoint, or `null` to reject it.
12
+ * Without it, endpoint requests use the auth, fetch and middleware settings of `submodelRepositoryConfig`.
13
+ */
14
+ endpointConfiguration?: EndpointConfigurationResolver;
9
15
  }
10
16
  export interface SubmodelListResolutionWarning {
11
17
  submodelIdentifier?: string;
@@ -28,6 +34,7 @@ export declare class SubmodelService {
28
34
  private submodelRegistryConfig?;
29
35
  private submodelRepositoryConfig?;
30
36
  private conceptDescriptionRepositoryConfig?;
37
+ private endpointConfiguration?;
31
38
  constructor(config: SubmodelServiceConfig);
32
39
  /**
33
40
  * Retrieves a list of all Submodels.
@@ -108,9 +115,10 @@ export declare class SubmodelService {
108
115
  *
109
116
  * Extracts the base URL and base64url-encoded Submodel identifier from the endpoint,
110
117
  * decodes the identifier, and fetches the submodel from the repository.
118
+ * If an `endpointConfiguration` hook is configured, it decides whether and how the endpoint is contacted.
111
119
  *
112
120
  * @param options Object containing:
113
- * - endpoint: The endpoint URL (format: http://host/submodels/{base64EncodedId})
121
+ * - endpoint: The endpoint URL (format: http://host[/basePath]/submodels/{base64EncodedId})
114
122
  * - includeConceptDescriptions?: Whether to fetch concept descriptions (default: false)
115
123
  *
116
124
  * @returns Either `{ success: true; data: { submodel, conceptDescriptions? }; etag? }` or `{ success: false; error: ... }`.
@@ -123,13 +131,6 @@ export declare class SubmodelService {
123
131
  submodel: Submodel;
124
132
  conceptDescriptions?: ConceptDescription[];
125
133
  }, 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;
133
134
  /**
134
135
  * Creates a Submodel and optionally registers it in the registry.
135
136
  *
@@ -2,9 +2,9 @@ import { ModelType } from '@aas-core-works/aas-core3.1-typescript/types';
2
2
  import { ConceptDescriptionRepositoryClient } from '../clients/ConceptDescriptionRepositoryClient';
3
3
  import { SubmodelRegistryClient } from '../clients/SubmodelRegistryClient';
4
4
  import { SubmodelRepositoryClient } from '../clients/SubmodelRepositoryClient';
5
- import { Configuration } from '../generated/runtime';
6
5
  import { base64Decode, base64Encode } from '../lib/base64Url';
7
6
  import { pickConditionalErrorFields } from '../lib/conditionalRequests';
7
+ import { createEndpointConfiguration, resolveDescriptorEndpoint, splitResourceHref, } from '../lib/endpointConfiguration';
8
8
  import { SubmodelDescriptor } from '../models/Descriptors';
9
9
  /**
10
10
  * SubmodelService combines Submodel Registry, Submodel Repository, and Concept Description Repository clients
@@ -21,6 +21,7 @@ export class SubmodelService {
21
21
  submodelRegistryConfig;
22
22
  submodelRepositoryConfig;
23
23
  conceptDescriptionRepositoryConfig;
24
+ endpointConfiguration;
24
25
  constructor(config) {
25
26
  this.submodelRegistryClient = new SubmodelRegistryClient();
26
27
  this.submodelRepositoryClient = new SubmodelRepositoryClient();
@@ -28,6 +29,7 @@ export class SubmodelService {
28
29
  this.submodelRegistryConfig = config.submodelRegistryConfig;
29
30
  this.submodelRepositoryConfig = config.submodelRepositoryConfig;
30
31
  this.conceptDescriptionRepositoryConfig = config.conceptDescriptionRepositoryConfig;
32
+ this.endpointConfiguration = config.endpointConfiguration;
31
33
  }
32
34
  /**
33
35
  * Retrieves a list of all Submodels.
@@ -75,14 +77,14 @@ export class SubmodelService {
75
77
  },
76
78
  };
77
79
  }
78
- const endpoint = descriptor.endpoints?.[0]?.protocolInformation?.href;
80
+ const endpoint = resolveDescriptorEndpoint(descriptor, 'SUBMODEL')?.href;
79
81
  if (!endpoint) {
80
82
  return {
81
83
  submodel: null,
82
84
  warning: {
83
85
  submodelIdentifier: descriptor.id,
84
86
  errorType: 'MissingEndpoint',
85
- message: 'Submodel descriptor has no endpoint and cannot be resolved',
87
+ message: 'Submodel descriptor has no SUBMODEL-3.x endpoint and cannot be resolved',
86
88
  },
87
89
  };
88
90
  }
@@ -203,7 +205,7 @@ export class SubmodelService {
203
205
  });
204
206
  if (descriptorResult.success) {
205
207
  const descriptor = descriptorResult.data;
206
- const endpoint = descriptor.endpoints?.[0]?.protocolInformation?.href;
208
+ const endpoint = resolveDescriptorEndpoint(descriptor, 'SUBMODEL')?.href;
207
209
  if (endpoint) {
208
210
  const submodelResult = await this.getSubmodelByEndpoint({
209
211
  endpoint,
@@ -281,7 +283,7 @@ export class SubmodelService {
281
283
  submodelIdentifier,
282
284
  });
283
285
  if (descriptorResult.success) {
284
- const endpoint = descriptorResult.data.endpoints?.[0]?.protocolInformation?.href;
286
+ const endpoint = resolveDescriptorEndpoint(descriptorResult.data, 'SUBMODEL')?.href;
285
287
  if (endpoint) {
286
288
  return { success: true, data: endpoint };
287
289
  }
@@ -307,9 +309,10 @@ export class SubmodelService {
307
309
  *
308
310
  * Extracts the base URL and base64url-encoded Submodel identifier from the endpoint,
309
311
  * decodes the identifier, and fetches the submodel from the repository.
312
+ * If an `endpointConfiguration` hook is configured, it decides whether and how the endpoint is contacted.
310
313
  *
311
314
  * @param options Object containing:
312
- * - endpoint: The endpoint URL (format: http://host/submodels/{base64EncodedId})
315
+ * - endpoint: The endpoint URL (format: http://host[/basePath]/submodels/{base64EncodedId})
313
316
  * - includeConceptDescriptions?: Whether to fetch concept descriptions (default: false)
314
317
  *
315
318
  * @returns Either `{ success: true; data: { submodel, conceptDescriptions? }; etag? }` or `{ success: false; error: ... }`.
@@ -319,8 +322,8 @@ export class SubmodelService {
319
322
  const { endpoint, includeConceptDescriptions = false } = options;
320
323
  // Extract base URL and encoded ID from endpoint
321
324
  // Expected format: http://localhost:8082/submodels/base64EncodedId
322
- const match = endpoint.match(/^(https?:\/\/[^/]+(?::\d+)?)\/submodels\/([^/]+)$/);
323
- if (!match) {
325
+ const parts = splitResourceHref(endpoint, 'submodels');
326
+ if (!parts) {
324
327
  return {
325
328
  success: false,
326
329
  error: {
@@ -329,7 +332,7 @@ export class SubmodelService {
329
332
  },
330
333
  };
331
334
  }
332
- const [, baseUrl, encodedId] = match;
335
+ const { basePath: baseUrl, encodedId } = parts;
333
336
  // Decode the ID
334
337
  let submodelIdentifier;
335
338
  try {
@@ -345,10 +348,13 @@ export class SubmodelService {
345
348
  };
346
349
  }
347
350
  // Create configuration for the endpoint
348
- const config = this.createRepositoryEndpointConfiguration(baseUrl);
351
+ const configResult = await createEndpointConfiguration(endpoint, baseUrl, this.endpointConfiguration, this.submodelRepositoryConfig);
352
+ if (!configResult.success) {
353
+ return { success: false, error: configResult.error };
354
+ }
349
355
  // Fetch the submodel
350
356
  const submodelResult = await this.submodelRepositoryClient.getSubmodelById({
351
- configuration: config,
357
+ configuration: configResult.configuration,
352
358
  submodelIdentifier,
353
359
  });
354
360
  if (!submodelResult.success) {
@@ -369,29 +375,6 @@ export class SubmodelService {
369
375
  etag: submodelResult.etag,
370
376
  };
371
377
  }
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
- }
395
378
  /**
396
379
  * Creates a Submodel and optionally registers it in the registry.
397
380
  *
@@ -1,3 +1,4 @@
1
+ export type { EndpointConfigurationResolver } from '../lib/endpointConfiguration';
1
2
  export type { AasServiceConfig } from './AasService';
2
3
  export { AasService } from './AasService';
3
4
  export type { SubmodelServiceConfig } from './SubmodelService';
@@ -1,6 +1,32 @@
1
- import { AssetAdministrationShellDescriptor, SubmodelDescriptor } from '../models/Descriptors';
1
+ import { AssetAdministrationShellDescriptor, Endpoint, SubmodelDescriptor } from '../models/Descriptors';
2
+ /**
3
+ * Finds the endpoint of a descriptor that matches the given interface short name.
4
+ *
5
+ * An exact match on `endpoint._interface` is preferred. For `AAS-3.x` and `SUBMODEL-3.x` requests,
6
+ * other 3.x versions are accepted as well, in this order:
7
+ * 1. exact match (e.g. `AAS-3.0`)
8
+ * 2. any direct interface of major version 3 (e.g. `AAS-3.1`, `AAS-3.2`)
9
+ * 3. the repository interface of the same version (e.g. `AAS-REPOSITORY-3.0`)
10
+ * 4. any repository interface of major version 3 (e.g. `AAS-REPOSITORY-3.2`)
11
+ *
12
+ * The href of a repository interface points to the repository base path instead of the resource itself.
13
+ *
14
+ * @param {Object} descriptor - The descriptor containing endpoint information.
15
+ * @param {string} interfaceShortName - The short name of the interface to match against endpoint interfaces.
16
+ * @returns {Endpoint | undefined} The matching endpoint, or `undefined` if there is none.
17
+ */
18
+ export declare function findEndpoint(descriptor: AssetAdministrationShellDescriptor | SubmodelDescriptor, interfaceShortName: string): Endpoint | undefined;
19
+ /**
20
+ * Checks whether an endpoint uses a repository interface (e.g. `AAS-REPOSITORY-3.0`).
21
+ * The href of such an endpoint points to the repository base path instead of the resource itself.
22
+ *
23
+ * @param {Endpoint} endpoint - The endpoint to check.
24
+ * @returns {boolean} `true` if the endpoint uses a repository interface.
25
+ */
26
+ export declare function isRepositoryEndpoint(endpoint: Endpoint): boolean;
2
27
  /**
3
28
  * Extracts the endpoint from a descriptor based on the given interface short name.
29
+ * See {@link findEndpoint} for the order in which endpoints are matched.
4
30
  *
5
31
  * @param {Object} descriptor - The descriptor containing endpoint information.
6
32
  * @param {string} interfaceShortName - The short name of the interface to match against endpoint interfaces.
@@ -1,37 +1,75 @@
1
+ const interfaceShortNames = [
2
+ 'AAS',
3
+ 'SUBMODEL',
4
+ 'SERIALIZE',
5
+ 'DESCRIPTION',
6
+ 'AASX-FILE',
7
+ 'AAS-REGISTRY',
8
+ 'SUBMODEL-REGISTRY',
9
+ 'AAS-REPOSITORY',
10
+ 'SUBMODEL-REPOSITORY',
11
+ 'CD-REPOSITORY',
12
+ 'AAS-DISCOVERY',
13
+ ];
1
14
  /**
2
- * Extracts the endpoint from a descriptor based on the given interface short name.
15
+ * Finds the endpoint of a descriptor that matches the given interface short name.
16
+ *
17
+ * An exact match on `endpoint._interface` is preferred. For `AAS-3.x` and `SUBMODEL-3.x` requests,
18
+ * other 3.x versions are accepted as well, in this order:
19
+ * 1. exact match (e.g. `AAS-3.0`)
20
+ * 2. any direct interface of major version 3 (e.g. `AAS-3.1`, `AAS-3.2`)
21
+ * 3. the repository interface of the same version (e.g. `AAS-REPOSITORY-3.0`)
22
+ * 4. any repository interface of major version 3 (e.g. `AAS-REPOSITORY-3.2`)
23
+ *
24
+ * The href of a repository interface points to the repository base path instead of the resource itself.
3
25
  *
4
26
  * @param {Object} descriptor - The descriptor containing endpoint information.
5
27
  * @param {string} interfaceShortName - The short name of the interface to match against endpoint interfaces.
6
- * @returns {string} The href of the matching endpoint's protocol information if found, otherwise an empty string.
28
+ * @returns {Endpoint | undefined} The matching endpoint, or `undefined` if there is none.
7
29
  */
8
- export function extractEndpointHref(descriptor, interfaceShortName) {
9
- const failResponse = '';
10
- const interfaceShortNames = [
11
- 'AAS',
12
- 'SUBMODEL',
13
- 'SERIALIZE',
14
- 'DESCRIPTION',
15
- 'AASX-FILE',
16
- 'AAS-REGISTRY',
17
- 'SUBMODEL-REGISTRY',
18
- 'AAS-REPOSITORY',
19
- 'SUBMODEL-REPOSITORY',
20
- 'CD-REPOSITORY',
21
- 'AAS-DISCOVERY',
22
- ];
30
+ export function findEndpoint(descriptor, interfaceShortName) {
23
31
  if (!interfaceShortName || interfaceShortName.trim() === '')
24
- return failResponse;
25
- interfaceShortName = interfaceShortName.trim();
26
- interfaceShortName = interfaceShortName.toUpperCase();
32
+ return undefined;
33
+ interfaceShortName = interfaceShortName.trim().toUpperCase();
27
34
  if (!interfaceShortNames.some((iShortName) => interfaceShortName.startsWith(`${iShortName}-`))) {
28
- return failResponse;
35
+ return undefined;
29
36
  }
30
- if (!Array.isArray(descriptor?.endpoints) || descriptor?.endpoints.length === 0) {
31
- return failResponse;
37
+ if (!Array.isArray(descriptor?.endpoints) || descriptor.endpoints.length === 0) {
38
+ return undefined;
32
39
  }
33
- const endpoints = descriptor.endpoints;
34
- // find the right endpoint based on the interfaceShortName (has to match endpoint.interface)
35
- const endpoint = endpoints.find((endpoint) => endpoint?._interface === interfaceShortName);
36
- return endpoint?.protocolInformation?.href ? endpoint.protocolInformation.href : '';
40
+ const endpoints = descriptor.endpoints.filter((endpoint) => endpoint?.protocolInformation?.href);
41
+ const interfaceOf = (endpoint) => endpoint._interface?.trim().toUpperCase();
42
+ const exactMatch = endpoints.find((endpoint) => interfaceOf(endpoint) === interfaceShortName);
43
+ if (exactMatch)
44
+ return exactMatch;
45
+ const versionedInterface = /^(AAS|SUBMODEL)-(3\.\d+(?:\.\d+)*)$/.exec(interfaceShortName);
46
+ if (!versionedInterface)
47
+ return undefined;
48
+ const [, interfaceName, version] = versionedInterface;
49
+ const directInterfacePattern = new RegExp(String.raw `^${interfaceName}-3\.\d+(?:\.\d+)*$`);
50
+ const repositoryInterfacePattern = new RegExp(String.raw `^${interfaceName}-REPOSITORY-3\.\d+(?:\.\d+)*$`);
51
+ return (endpoints.find((endpoint) => directInterfacePattern.test(interfaceOf(endpoint) ?? '')) ??
52
+ endpoints.find((endpoint) => interfaceOf(endpoint) === `${interfaceName}-REPOSITORY-${version}`) ??
53
+ endpoints.find((endpoint) => repositoryInterfacePattern.test(interfaceOf(endpoint) ?? '')));
54
+ }
55
+ /**
56
+ * Checks whether an endpoint uses a repository interface (e.g. `AAS-REPOSITORY-3.0`).
57
+ * The href of such an endpoint points to the repository base path instead of the resource itself.
58
+ *
59
+ * @param {Endpoint} endpoint - The endpoint to check.
60
+ * @returns {boolean} `true` if the endpoint uses a repository interface.
61
+ */
62
+ export function isRepositoryEndpoint(endpoint) {
63
+ return /^[A-Z-]+-REPOSITORY-/.test(endpoint?._interface?.trim().toUpperCase() ?? '');
64
+ }
65
+ /**
66
+ * Extracts the endpoint from a descriptor based on the given interface short name.
67
+ * See {@link findEndpoint} for the order in which endpoints are matched.
68
+ *
69
+ * @param {Object} descriptor - The descriptor containing endpoint information.
70
+ * @param {string} interfaceShortName - The short name of the interface to match against endpoint interfaces.
71
+ * @returns {string} The href of the matching endpoint's protocol information if found, otherwise an empty string.
72
+ */
73
+ export function extractEndpointHref(descriptor, interfaceShortName) {
74
+ return findEndpoint(descriptor, interfaceShortName)?.protocolInformation?.href ?? '';
37
75
  }
@@ -0,0 +1,30 @@
1
+ /**
2
+ * The query endpoints of the AAS API.
3
+ */
4
+ export type QueryEndpoint = 'shells' | 'submodels' | 'shell-descriptors' | 'submodel-descriptors' | 'concept-descriptions';
5
+ /**
6
+ * Returns the query endpoints whose query profile a service advertises in its `ServiceDescription`.
7
+ *
8
+ * Profiles are matched by service specification and profile number, regardless of host and API version (both
9
+ * `https://admin-shell.io/aas/API/3/2/...` and `https://basyx.org/aas/API/3/2/...`). This is a best-effort hint: a
10
+ * server can serve query endpoints without advertising their profile, so an empty result does not prove that queries
11
+ * are unsupported.
12
+ *
13
+ * @param serviceDescription The result of `getSelfDescription`
14
+ * @returns The query endpoints with an advertised profile
15
+ */
16
+ export declare function getQueryEndpoints(serviceDescription: {
17
+ profiles?: Array<string> | null;
18
+ } | null | undefined): QueryEndpoint[];
19
+ /**
20
+ * Checks whether a service advertises the query profile for an endpoint, or for any query endpoint if none is given.
21
+ *
22
+ * This is a best-effort hint, see {@link getQueryEndpoints}.
23
+ *
24
+ * @param serviceDescription The result of `getSelfDescription`
25
+ * @param endpoint The query endpoint, e.g. `'shells'` for `/query/shells`
26
+ * @returns `true` if the matching query profile is advertised
27
+ */
28
+ export declare function supportsQuery(serviceDescription: {
29
+ profiles?: Array<string> | null;
30
+ } | null | undefined, endpoint?: QueryEndpoint): boolean;
@@ -0,0 +1,43 @@
1
+ // The service specification profile that adds each query endpoint, the same in API versions 3.1 and 3.2.
2
+ const QUERY_PROFILES = {
3
+ shells: { specification: 'AssetAdministrationShellRepositoryServiceSpecification', profile: 'SSP-003' },
4
+ submodels: { specification: 'SubmodelRepositoryServiceSpecification', profile: 'SSP-005' },
5
+ 'shell-descriptors': { specification: 'AssetAdministrationShellRegistryServiceSpecification', profile: 'SSP-004' },
6
+ 'submodel-descriptors': { specification: 'SubmodelRegistryServiceSpecification', profile: 'SSP-004' },
7
+ 'concept-descriptions': { specification: 'ConceptDescriptionRepositoryServiceSpecification', profile: 'SSP-002' },
8
+ };
9
+ // e.g. https://admin-shell.io/aas/API/3/1/SubmodelRepositoryServiceSpecification/SSP-005
10
+ const PROFILE_PATTERN = /\/aas\/API\/3\/\d+\/([A-Za-z]+)\/(SSP-\d+)$/;
11
+ /**
12
+ * Returns the query endpoints whose query profile a service advertises in its `ServiceDescription`.
13
+ *
14
+ * Profiles are matched by service specification and profile number, regardless of host and API version (both
15
+ * `https://admin-shell.io/aas/API/3/2/...` and `https://basyx.org/aas/API/3/2/...`). This is a best-effort hint: a
16
+ * server can serve query endpoints without advertising their profile, so an empty result does not prove that queries
17
+ * are unsupported.
18
+ *
19
+ * @param serviceDescription The result of `getSelfDescription`
20
+ * @returns The query endpoints with an advertised profile
21
+ */
22
+ export function getQueryEndpoints(serviceDescription) {
23
+ const profiles = serviceDescription?.profiles ?? [];
24
+ return Object.keys(QUERY_PROFILES).filter((endpoint) => profiles.some((profile) => {
25
+ const match = PROFILE_PATTERN.exec(profile);
26
+ return (match !== null &&
27
+ match[1] === QUERY_PROFILES[endpoint].specification &&
28
+ match[2] === QUERY_PROFILES[endpoint].profile);
29
+ }));
30
+ }
31
+ /**
32
+ * Checks whether a service advertises the query profile for an endpoint, or for any query endpoint if none is given.
33
+ *
34
+ * This is a best-effort hint, see {@link getQueryEndpoints}.
35
+ *
36
+ * @param serviceDescription The result of `getSelfDescription`
37
+ * @param endpoint The query endpoint, e.g. `'shells'` for `/query/shells`
38
+ * @returns `true` if the matching query profile is advertised
39
+ */
40
+ export function supportsQuery(serviceDescription, endpoint) {
41
+ const endpoints = getQueryEndpoints(serviceDescription);
42
+ return endpoint === undefined ? endpoints.length > 0 : endpoints.includes(endpoint);
43
+ }
@@ -4,9 +4,11 @@ export * from './MultiLanguagePropertyUtils';
4
4
  export * from './ReferableUtils';
5
5
  export * from './ReferenceUtil';
6
6
  export * from './SemanticIdUtils';
7
+ export * from './ServiceDescriptionUtils';
7
8
  export * as DescriptorUtils from './DescriptorUtils';
8
9
  export * as KeyTypesUtil from './KeyTypesUtil';
9
10
  export * as MultiLanguagePropertyUtils from './MultiLanguagePropertyUtils';
10
11
  export * as ReferableUtils from './ReferableUtils';
11
12
  export * as ReferenceUtil from './ReferenceUtil';
12
13
  export * as SemanticIdUtils from './SemanticIdUtils';
14
+ export * as ServiceDescriptionUtils from './ServiceDescriptionUtils';
@@ -5,6 +5,7 @@ export * from './MultiLanguagePropertyUtils';
5
5
  export * from './ReferableUtils';
6
6
  export * from './ReferenceUtil';
7
7
  export * from './SemanticIdUtils';
8
+ export * from './ServiceDescriptionUtils';
8
9
  // Also export as namespaces for organized imports
9
10
  export * as DescriptorUtils from './DescriptorUtils';
10
11
  export * as KeyTypesUtil from './KeyTypesUtil';
@@ -12,3 +13,4 @@ export * as MultiLanguagePropertyUtils from './MultiLanguagePropertyUtils';
12
13
  export * as ReferableUtils from './ReferableUtils';
13
14
  export * as ReferenceUtil from './ReferenceUtil';
14
15
  export * as SemanticIdUtils from './SemanticIdUtils';
16
+ export * as ServiceDescriptionUtils from './ServiceDescriptionUtils';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "basyx-typescript-sdk",
3
- "version": "2.3.1",
3
+ "version": "2.4.1",
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",