# SHIELD - TypeScript SDK

This SDK provides a convenient TypeScript client for interacting with the SHI SHIELD service. It is automatically generated from the OpenAPI specification located at [`SHIELD.json`](https://github.com/Software-Hardware-Integration-Lab/OpenAPI/blob/main/specs/SHIELD.json) using [Kiota](https://github.com/microsoft/kiota).

All typing data is included in the package.

## Installation

Install the SDK using npm:

```bash
npm install @shi-corp/sdk-shield
```

## Usage

Here's a basic example of how to use the SDK:

```TypeScript
import { DefaultAzureCredential } from '@azure/identity'
import { shieldClientFactory } from '@shi-corp/sdk-shield';

/** Authentication session used to authenticate to SHIELD. */
const credential = new DefaultAzureCredential();

/** Base URL for your SHIELD instance. Protocol specifier (`http`/`https`) is required, even for localhost. */
const baseUrl = new URL('https://shield.example.com');

/**
 * Configured client for SHIELD that can make authenticated web requests against SDG.
 *
 * The third param, the scope is the `Application ID` of the `SHIELD - End User Login` app registration. This can also be found on SHIELD's `/Api/Auth/Id` endpoint.
 */
const shieldClient = shieldClientFactory(credential, baseUrl, ['b9689d4e-0036-4f2f-8430-07adedb9ae7c/.default']);

/** Flag that indicates if discover is currently running (`true`) or not (`false`). */
const results = await shieldClient.api.discover.status.get();

// Check if discover is currently running
if (results?.running === true) {
    // Do something
}
```

### Advanced Usage

You can optionally configure the SDK client with a custom base URL, including support for it being nested deep in a L7 load balancer:

```TypeScript
/** Custom host and endpoint base to as an example for something behind a layer 7 load balancer, E.g. Azure App Gateway or Azure API Gateway. If in debug mode, run against localhost. */
const customBaseUrl = debugMode ? new URL('http://localhost:3000') : new URL('https://custom-host.example.com/Ballance/Instance1/');

/** Configured instance of the SHIELD client. */
const customConfiguredClient = shieldClientFactory(credential, customBaseUrl);
```

and/or scope (permission) list:

```TypeScript
/**
 * `.default` and explicit permissions can't exist in the same custom scope list at the same time, Entra ID doesn't support this.
 *
 * If not providing the `.default` scope, you can have any number of scopes (permissions) listed in different array indexes.
 */
const customScopes = ['your-custom-scope/something.read.all', 'your-custom-scope/everything.readwrite.all'];

// Initialize the SDK client with custom configuration.
const customConfiguredClient = shieldClientFactory(credential, void 0, customScopes);
```

## Project Structure

- `bin/`: Compiled JavaScript files and type definitions.
- `sdk/`: Source TypeScript files generated by Kiota.
  - `api/`: API endpoint definitions.
  - `models/`: Data models used by the SDK.

## Development

### Prerequisites

- [Node.js](https://nodejs.org/) - Latest LTS version
- [Kiota](https://github.com/microsoft/kiota)

### Generating the SDK

To regenerate the SDK from the OpenAPI specification, run:

```bash
npm run generate:Sdk
```

### Building the SDK

To build the SDK for production, run:

```bash
npm run build:Prod
```

## License

This SDK is licensed under the [MIT License](./LICENSE).

## Support

For issues or feature requests, please visit the [GitHub Issues page](https://github.com/Software-Hardware-Integration-Lab/OpenAPI/issues).

For more information, visit the [official documentation](https://docs.shilab.com).