basyx-typescript-sdk 1.0.1 → 1.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -9,6 +9,16 @@ BaSyx TypeScript SDK for developing applications and components for the Asset Ad
9
9
 
10
10
  ## Features
11
11
 
12
+ High-level orchestration services:
13
+ - **AasService**: Unified API for AAS operations across registry and repository
14
+ - Create, read, update, delete AAS with automatic registry synchronization
15
+ - Fetch AAS with their submodels in a single call
16
+ - Automatic endpoint resolution and fallback handling
17
+ - **SubmodelService**: Unified API for Submodel operations across registry and repository
18
+ - Create, read, update, delete Submodels with automatic registry synchronization
19
+ - Flexible endpoint-based retrieval
20
+ - Automatic fallback to repository when registry unavailable
21
+
12
22
  Clients for the AAS API components:
13
23
  - AAS Repository
14
24
  - Submodel Repository
@@ -47,7 +57,58 @@ npm install @aas-core-works/aas-core3.0-typescript
47
57
  yarn add @aas-core-works/aas-core3.0-typescript
48
58
  ```
49
59
 
50
- ## Usage Example
60
+ ## Import Styles
61
+
62
+ The SDK supports multiple import styles for flexibility:
63
+
64
+ ### Direct Imports (Recommended for most use cases)
65
+
66
+ ```typescript
67
+ // Import clients directly
68
+ import { AasRepositoryClient, AasRegistryClient, Configuration } from 'basyx-typescript-sdk';
69
+
70
+ // Import services directly
71
+ import { AasService } from 'basyx-typescript-sdk';
72
+
73
+ // Import utility functions directly
74
+ import { extractEndpointHref, getSubmodelElementByIdShort } from 'basyx-typescript-sdk';
75
+
76
+ // Import library functions directly
77
+ import { base64Encode, base64Decode } from 'basyx-typescript-sdk';
78
+ ```
79
+
80
+ ### Namespaced Imports (For organized code)
81
+
82
+ ```typescript
83
+ // Import utilities as namespace
84
+ import { Utils, Lib } from 'basyx-typescript-sdk';
85
+
86
+ // Use with namespace
87
+ const endpoint = Utils.extractEndpointHref(descriptor, 'AAS-3.0');
88
+ const encoded = Lib.base64Encode('my-id');
89
+ ```
90
+
91
+ ### Mixed Style
92
+
93
+ ```typescript
94
+ // Combine direct and namespaced imports
95
+ import {
96
+ AasService,
97
+ Configuration,
98
+ Utils,
99
+ base64Encode
100
+ } from 'basyx-typescript-sdk';
101
+
102
+ // Use directly imported functions
103
+ const id = base64Encode('my-id');
104
+
105
+ // Use namespaced utilities
106
+ const element = Utils.getSubmodelElementByIdShort(submodel, 'myElement');
107
+ ```
108
+
109
+ ## Usage Examples
110
+
111
+ ### Basic Client Usage
51
112
 
52
113
  ```typescript
53
114
  import { AasRepositoryClient, Configuration } from 'basyx-typescript-sdk';
@@ -58,14 +119,325 @@ async function getAllShells() {
58
119
  basePath: 'http://localhost:8081',
59
120
  });
60
121
 
61
- try {
62
- const response = await client.getAllAssetAdministrationShells({ configuration });
63
- console.log('Asset Administration Shells fetched successfully:', response);
64
- // You can now use the response as needed
65
- } catch (error) {
66
- console.error('Error fetching Asset Administration Shells:', error);
122
+ const response = await client.getAllAssetAdministrationShells({ configuration });
123
+
124
+ if (response.success) {
125
+ console.log('Shells:', response.data.result);
126
+ } else {
127
+ console.error('Error:', response.error);
67
128
  }
68
129
  }
130
+ ```
131
+
132
+ ### Using the AasService (High-level API)
133
+
134
+ ```typescript
135
+ import { AasService, Configuration } from 'basyx-typescript-sdk';
136
+ import { AssetAdministrationShell, AssetInformation, AssetKind } from '@aas-core-works/aas-core3.0-typescript/types';
137
+
138
+ // Initialize service with both registry and repository
139
+ const service = new AasService({
140
+ registryConfig: new Configuration({ basePath: 'http://localhost:8084' }),
141
+ repositoryConfig: new Configuration({ basePath: 'http://localhost:8081' }),
142
+ // Optional: Separate configs for submodel services (used when includeSubmodels is enabled)
143
+ // If not provided, falls back to using registryConfig/repositoryConfig for submodels
144
+ // In typical BaSyx deployments, submodel services run on different ports:
145
+ submodelRegistryConfig: new Configuration({ basePath: 'http://localhost:8083' }),
146
+ submodelRepositoryConfig: new Configuration({ basePath: 'http://localhost:8081' }),
147
+ // Optional: Discovery service config (used for asset ID lookups)
148
+ discoveryConfig: new Configuration({ basePath: 'http://localhost:8086' }),
149
+ });
150
+
151
+ // Create a new AAS (automatically registers in registry)
152
+ const shell = new AssetAdministrationShell(
153
+ 'https://example.com/ids/aas/my-aas',
154
+ new AssetInformation(AssetKind.Instance)
155
+ );
156
+
157
+ const createResult = await service.createAas({ shell });
158
+ if (createResult.success) {
159
+ console.log('Created AAS:', createResult.data.shell);
160
+ }
161
+
162
+ // Get AAS list from registry with automatic endpoint resolution
163
+ const listResult = await service.getAasList();
164
+ if (listResult.success) {
165
+ console.log('All shells:', listResult.data.shells);
166
+ }
167
+
168
+ // Get AAS by ID (uses registry endpoint if available)
169
+ const getResult = await service.getAasById({
170
+ aasIdentifier: 'https://example.com/ids/aas/my-aas'
171
+ });
172
+
173
+ // Get AAS with its submodels in a single call
174
+ const withSubmodels = await service.getAasById({
175
+ aasIdentifier: 'https://example.com/ids/aas/my-aas',
176
+ includeSubmodels: true
177
+ });
178
+ if (withSubmodels.success) {
179
+ console.log('Shell:', withSubmodels.data.shell);
180
+ console.log('Submodels:', withSubmodels.data.submodels); // Array of submodels
181
+ }
182
+
183
+ // Get all AAS with their submodels
184
+ const allWithSubmodels = await service.getAasList({ includeSubmodels: true });
185
+ if (allWithSubmodels.success) {
186
+ allWithSubmodels.data.shells.forEach((shell, index) => {
187
+ console.log(`Shell ${index}:`, shell.id);
188
+ console.log(`Submodels:`, allWithSubmodels.data.submodels?.[shell.id]);
189
+ });
190
+ }
191
+
192
+ // Update AAS (updates both repository and registry)
193
+ shell.idShort = 'UpdatedName';
194
+ const updateResult = await service.updateAas({ shell });
195
+
196
+ // Get endpoint for an AAS
197
+ const endpointResult = await service.getAasEndpointById({
198
+ aasIdentifier: 'https://example.com/ids/aas/my-aas'
199
+ });
200
+
201
+ // Get AAS directly by endpoint URL
202
+ const byEndpointResult = await service.getAasByEndpoint({
203
+ endpoint: 'http://localhost:8081/shells/encoded-id'
204
+ });
205
+
206
+ // Delete AAS (removes from both registry and repository)
207
+ await service.deleteAas({
208
+ aasIdentifier: 'https://example.com/ids/aas/my-aas'
209
+ });
210
+
211
+ // Find AAS by asset IDs using discovery service
212
+ const assetIds = [
213
+ { name: 'serialNumber', value: '12345' },
214
+ { name: 'deviceId', value: 'device-001' },
215
+ ];
216
+
217
+ const byAssetIdResult = await service.getAasByAssetId({
218
+ assetIds,
219
+ includeSubmodels: true // Optionally include submodels
220
+ });
221
+ if (byAssetIdResult.success) {
222
+ console.log('Found AAS IDs:', byAssetIdResult.data.aasIds);
223
+ console.log('Found shells:', byAssetIdResult.data.shells);
224
+ // If multiple AAS match the asset IDs, all are returned
225
+ }
226
+
227
+ // Fetch AAS with submodels and their concept descriptions
228
+ const serviceWithCD = new AasService({
229
+ registryConfig: new Configuration({ basePath: 'http://localhost:8084' }),
230
+ repositoryConfig: new Configuration({ basePath: 'http://localhost:8081' }),
231
+ submodelRegistryConfig: new Configuration({ basePath: 'http://localhost:8085' }),
232
+ submodelRepositoryConfig: new Configuration({ basePath: 'http://localhost:8082' }),
233
+ conceptDescriptionRepositoryConfig: new Configuration({ basePath: 'http://localhost:8083' }),
234
+ });
235
+
236
+ const withConceptDescriptions = await serviceWithCD.getAasById({
237
+ aasIdentifier: 'https://example.com/ids/aas/my-aas',
238
+ includeSubmodels: true,
239
+ includeConceptDescriptions: true,
240
+ });
241
+ if (withConceptDescriptions.success) {
242
+ console.log('Shell:', withConceptDescriptions.data.shell);
243
+ console.log('Submodels with CDs:', withConceptDescriptions.data.submodels);
244
+ // Concept descriptions are fetched for all semantic IDs in submodels and their elements
245
+ }
246
+
247
+ // Resolve a Reference to get endpoints for AAS, Submodel, or SubmodelElement
248
+ import { Reference, Key, KeyTypes, ReferenceTypes } from '@aas-core-works/aas-core3.0-typescript/types';
249
+
250
+ // Example 1: Reference to AAS and Submodel
251
+ const reference1 = new Reference(
252
+ ReferenceTypes.ModelReference,
253
+ [
254
+ new Key(KeyTypes.AssetAdministrationShell, 'https://example.com/ids/aas/my-aas'),
255
+ new Key(KeyTypes.Submodel, 'https://example.com/ids/sm/my-submodel'),
256
+ ]
257
+ );
258
+
259
+ const resolved1 = await service.resolveReference({ reference: reference1 });
260
+ if (resolved1.success) {
261
+ console.log('AAS Endpoint:', resolved1.data.aasEndpoint);
262
+ // e.g., 'http://localhost:8081/shells/encoded-aas-id'
263
+ console.log('Submodel Endpoint:', resolved1.data.submodelEndpoint);
264
+ // e.g., 'http://localhost:8082/submodels/encoded-sm-id'
265
+ }
266
+
267
+ // Example 2: Reference to a specific SubmodelElement
268
+ const reference2 = new Reference(
269
+ ReferenceTypes.ModelReference,
270
+ [
271
+ new Key(KeyTypes.AssetAdministrationShell, 'https://example.com/ids/aas/my-aas'),
272
+ new Key(KeyTypes.Submodel, 'https://example.com/ids/sm/my-submodel'),
273
+ new Key(KeyTypes.Property, 'MyProperty'),
274
+ ]
275
+ );
276
+
277
+ const resolved2 = await service.resolveReference({ reference: reference2 });
278
+ if (resolved2.success) {
279
+ console.log('SubmodelElement Path:', resolved2.data.submodelElementPath);
280
+ // e.g., 'http://localhost:8082/submodels/encoded-sm-id/submodel-elements/MyProperty'
281
+ }
282
+
283
+ // Example 3: Reference to nested SubmodelElements
284
+ const reference3 = new Reference(
285
+ ReferenceTypes.ModelReference,
286
+ [
287
+ new Key(KeyTypes.Submodel, 'https://example.com/ids/sm/my-submodel'),
288
+ new Key(KeyTypes.SubmodelElementCollection, 'MyCollection'),
289
+ new Key(KeyTypes.Property, 'NestedProperty'),
290
+ ]
291
+ );
292
+
293
+ const resolved3 = await service.resolveReference({ reference: reference3 });
294
+ if (resolved3.success) {
295
+ console.log('SubmodelElement Path:', resolved3.data.submodelElementPath);
296
+ // e.g., 'http://localhost:8082/submodels/encoded-sm-id/submodel-elements/MyCollection.NestedProperty'
297
+ }
298
+
299
+ // Fetch all AAS with submodels and concept descriptions
300
+ const allWithCD = await serviceWithCD.getAasList({
301
+ includeSubmodels: true,
302
+ includeConceptDescriptions: true,
303
+ });
304
+ if (allWithCD.success) {
305
+ allWithCD.data.shells.forEach((shell) => {
306
+ console.log('Shell:', shell.id);
307
+ console.log('Submodels:', allWithCD.data.submodels?.[shell.id]);
308
+ // Concept descriptions are available through the submodel service
309
+ });
310
+ }
311
+ ```
312
+
313
+ ### Using the SubmodelService (High-level API)
314
+
315
+ ```typescript
316
+ import { SubmodelService, Configuration } from 'basyx-typescript-sdk';
317
+ import { Submodel, ModellingKind } from '@aas-core-works/aas-core3.0-typescript/types';
318
+
319
+ // Initialize service with both registry and repository
320
+ const service = new SubmodelService({
321
+ registryConfig: new Configuration({ basePath: 'http://localhost:8085' }),
322
+ repositoryConfig: new Configuration({ basePath: 'http://localhost:8082' }),
323
+ });
324
+
325
+ // Create a new Submodel (automatically registers in registry)
326
+ const submodel = new Submodel(
327
+ 'https://example.com/ids/sm/my-submodel',
328
+ null, // extensions
329
+ null, // category
330
+ 'MySubmodel', // idShort
331
+ null, // displayName
332
+ null, // description
333
+ null, // administration
334
+ ModellingKind.Instance
335
+ );
336
+
337
+ const createResult = await service.createSubmodel({ submodel });
338
+ if (createResult.success) {
339
+ console.log('Created Submodel:', createResult.data.submodel);
340
+ console.log('Registry Descriptor:', createResult.data.descriptor);
341
+ }
342
+
343
+ // Get Submodel list from registry with automatic endpoint resolution
344
+ const listResult = await service.getSubmodelList({ preferRegistry: true });
345
+ if (listResult.success) {
346
+ console.log('All submodels:', listResult.data.submodels);
347
+ console.log('Fetched from:', listResult.data.source); // 'registry' or 'repository'
348
+ }
349
+
350
+ // Get Submodel by ID (uses registry endpoint if available)
351
+ const getResult = await service.getSubmodelById({
352
+ submodelIdentifier: 'https://example.com/ids/sm/my-submodel',
353
+ useRegistryEndpoint: true
354
+ });
355
+ if (getResult.success) {
356
+ console.log('Submodel:', getResult.data.submodel);
357
+ console.log('Descriptor:', getResult.data.descriptor);
358
+ }
359
+
360
+ // Update Submodel (updates both repository and registry)
361
+ submodel.idShort = 'UpdatedSubmodel';
362
+ const updateResult = await service.updateSubmodel({ submodel });
363
+
364
+ // Get endpoint for a Submodel
365
+ const endpointResult = await service.getSubmodelEndpointById({
366
+ submodelIdentifier: 'https://example.com/ids/sm/my-submodel'
367
+ });
368
+ if (endpointResult.success) {
369
+ console.log('Endpoint:', endpointResult.data);
370
+ }
371
+
372
+ // Get Submodel directly by endpoint URL
373
+ const byEndpointResult = await service.getSubmodelByEndpoint({
374
+ endpoint: 'http://localhost:8082/submodels/encoded-id'
375
+ });
376
+
377
+ // Delete Submodel (removes from both registry and repository)
378
+ await service.deleteSubmodel({
379
+ submodelIdentifier: 'https://example.com/ids/sm/my-submodel'
380
+ });
381
+
382
+ // Service works with only repository (no registry)
383
+ const repoOnlyService = new SubmodelService({
384
+ repositoryConfig: new Configuration({ basePath: 'http://localhost:8082' })
385
+ });
386
+
387
+ const repoList = await repoOnlyService.getSubmodelList();
388
+ // Automatically falls back to repository when registry unavailable
389
+
390
+ // Fetch submodels with concept descriptions
391
+ const serviceWithCD = new SubmodelService({
392
+ registryConfig: new Configuration({ basePath: 'http://localhost:8085' }),
393
+ repositoryConfig: new Configuration({ basePath: 'http://localhost:8082' }),
394
+ conceptDescriptionRepositoryConfig: new Configuration({ basePath: 'http://localhost:8083' }),
395
+ });
396
+
397
+ // Get submodel with its concept descriptions
398
+ const withCD = await serviceWithCD.getSubmodelById({
399
+ submodelIdentifier: 'https://example.com/ids/sm/my-submodel',
400
+ includeConceptDescriptions: true,
401
+ });
402
+ if (withCD.success) {
403
+ console.log('Submodel:', withCD.data.submodel);
404
+ console.log('Concept Descriptions:', withCD.data.conceptDescriptions);
405
+ // conceptDescriptions array contains all unique CDs referenced by:
406
+ // - The submodel's semanticId
407
+ // - All submodel elements' semanticId properties (recursively through collections, lists, entities)
408
+ }
409
+
410
+ // Get all submodels with concept descriptions
411
+ const listWithCD = await serviceWithCD.getSubmodelList({
412
+ preferRegistry: false,
413
+ includeConceptDescriptions: true,
414
+ });
415
+ if (listWithCD.success) {
416
+ console.log('Submodels:', listWithCD.data.submodels);
417
+ console.log('All Concept Descriptions:', listWithCD.data.conceptDescriptions);
418
+ // Concept descriptions are deduplicated across all submodels
419
+ }
420
+
421
+ // Get submodel by endpoint with concept descriptions
422
+ const byEndpointWithCD = await serviceWithCD.getSubmodelByEndpoint({
423
+ endpoint: 'http://localhost:8082/submodels/encoded-id',
424
+ includeConceptDescriptions: true,
425
+ });
426
+ ```
427
+
428
+ ### Using Utility Functions
429
+
430
+ ```typescript
431
+ import { getSubmodelElementByIdShort, extractEndpointHref, base64Encode } from 'basyx-typescript-sdk';
432
+ import { Submodel } from '@aas-core-works/aas-core3.0-typescript/types';
433
+
434
+ // Get a submodel element by its idShort
435
+ const element = getSubmodelElementByIdShort(submodel, 'MyProperty');
436
+
437
+ // Extract endpoint from descriptor
438
+ const endpoint = extractEndpointHref(descriptor, 'AAS-3.0');
69
439
 
70
- getAllShells();
440
+ // Encode/decode IDs from Identifiables
441
+ const encoded = base64Encode('https://example.com/ids/aas/my-aas');
442
+ // Use in URL: http://localhost:8081/shells/{encoded}
71
443
  ```