@leisoft/aas-client/README.md

TypeScript / JavaScript AAS metamodel and client library by Leisoft for both browser and Node.js.

# Leisoft AAS Client Library

TypeScript / JavaScript AAS metamodel and client library by Leisoft for both browser and Node.js.

![License](https://img.shields.io/badge/license-custom-important)

## Table of Contents

- [Introduction](#introduction)
- [Features Overview](#features-overview)
- [Metamodel](#metamodel)
- [Client](#client)
- [Treemodel](#treemodel)
- [ID Creation](#id-creation)
- [Version](#version)
- [AAS Compatibility](#aas-compatibility)
- [License](#license)
- [Credits](#credits)

## Introduction

```ts
const assetId = new LeisoftAasId();
assetId.idType = 'asset';
const shellId = LeisoftAasId.from(assetId);
shellId.idType = 'shell';
const shell: AssetAdministrationShell = {
    id: shellId.toUrl('https'),
    assetInformation: {
        assetKind: AssetKind.Instance,
        globalAssetId: assetId.toUrn(),
    },
    modelType: ModelType.AssetAdministrationShell,
    idShort: 'leisoftServer',
    displayName: [
        { language: 'en', text: 'Leisoft Server' },
    ],
};
const aasRepoClient = new AasRepoClient({
    protocol: AAS_REPO_PROTOCOL,
    host: AAS_REPO_SERVER,
    port: AAS_REPO_PORT,
});
try {
    await aasRepoClient.createShell(shell);
    console.log('AAS created successfully');
}
catch (error) {
    console.error('Error creating AAS:', (error as AasRequestError).messages);
}
```

## Features Overview
- AAS metamodel, descriptors, metadata, value only and REST specific types
- AAS client interfaces
    - AAS repository client
    - Submodel repository client
    - AAS registry client
    - Submodel registry client
    - Concept description repository client
    - Discovery API
    - Description API
- AAS tree model
- AAS compliant ID creation
- IdShortPath calculation

## Metamodel
TypeScript types for the entire AAS metamodel and the API specific types

```ts
const smId = new LeisoftAasId();
smId.idType = 'submodel';
const sm: Submodel = {
    id: smId.toUrn(),
    modelType: ModelType.Submodel,
    idShort: 'City',
    kind: ModellingKind.Instance,
    description: [
        { language: 'en', text: 'City of Tanna' },
        { language: 'de', text: 'Stadt Tanna' },
    ],
    submodelElements: [
        {
            modelType: ModelType.Property,
            idShort: 'CityName',
            value: 'Tanna',
            valueType: DataTypeDefXsd.String
        } as Property
    ]
};
console.log(JSON.parse(JSON.stringify(sm)));
```

## Client
All clients share the same base class and implement a specific service of the AAS API.

```ts
const smRepoClient = new SubmodelRepoClient({
    host: 'api.leisoft.de',
    port: 443,
    protocol: 'https',
    auth: {
        token: oidcClient.jwt
    } as TokenAuthParams
});
const streetNumber = await smRepoClient.getSubmodelElementValue(
    smId, 'address.street.number'
) as Property;
console.log(streetNumber.value);
```

## Treemodel
Using the AAS treemodel submodels and submodel element trees can be used like arrays and maps. IdShortPaths are calculated automatically and searches in the element tree are possible.

```ts
const smModel = new SubmodelTree(sm);
if (smModel.has('ManufacturerName')) {
    smModel.delete('ManufacturerName');
}
const sensorRange: Range = {
    idShort: 'SensorRange',
    modelType: ModelType.Range,
    min: String(8.5),
    max: String(31.2),
    valueType: DataTypeDefXsd.Decimal
};
smModel.set(sensorRange);

const phones = smModel.deepSearch(
    (element: SubmodelElement) => {
        return /^Leisoft-Car-.*$/i.test(element.idShort);
    },
    (element: SubmodelElement) => {
        const dm = langStringsToMap(element.description!);
        dm.set('en', translate(dm.get('de')!, 'en'));
        element.description = mapToLangStrings(dm);
    },
    4 // max depth
);
console.log(phones);
```

## ID Creation

Standard compliant ID creation for all identifiables in the AAS metamodel and beyond

- Sensible defaults
- Hierarchical structure for all use cases
- URL and URN generation

```ts
const id = new LeisoftAasId();
console.log(id.toUrn());
// urn:client.leisoft.de:entities:ids:88d0c3f7-e82e-4735-ac16-9237050d71b3

id.domain = 'project-x.leisoft.de';
id.idType = 'shell';
id.units = ['tanna', 'central', 'engineering'];
id.id = 'Leisoft-Tanna-Server-1';
console.log(id.toUrl('https'));
// https://project-x.leisoft.de/tanna/central/engineering/shells/ids/Leisoft-Tanna-Server-1
```

## Version

- (upcoming) 1.0.x first planned stable major release
- (current) 0.2.x initial preliminary release
- 0.1.0 test release

## AAS Compatibility

- AAS 3.0.x

## License

This project is licensed under the [Leisoft License](LICENSE).

## Credits

Developers:
- Christian Leistner (leistnerchr@web.de, [LinkedIn](https://www.linkedin.com/in/christian-leistner-a4550b223/))
- Johannes Rabausch