@shi-corp/sdk-shield

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 using Kiota.

All typing data is included in the package.

Installation

Install the SDK using npm:

npm install @shi-corp/sdk-shield

Usage

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

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:

/** 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:

/**
 * `.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 - Latest LTS version
• Kiota

Generating the SDK

To regenerate the SDK from the OpenAPI specification, run:

npm run-script generate:Sdk

Building the SDK

To build the SDK for production, run:

npm run-script build:Prod

License

This SDK is licensed under the MIT License.

Support

For issues or feature requests, please visit the GitHub Issues page.

For more information, visit the official documentation.