@shi-corp/sdk-url-shortener/README.md

SDK client used to interface with the URL Shortener application.

# URL Shortener - TypeScript SDK

This SDK provides a convenient TypeScript client for interacting with the SHI URL Shortener service. It is automatically generated from the OpenAPI specification located at [`Url-Shortener.json`](https://github.com/Software-Hardware-Integration-Lab/OpenAPI/blob/main/specs/Url-Shortener.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-url-shortener
```

## Usage

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

```TypeScript
import { DefaultAzureCredential } from '@azure/identity'
import { urlShortenerClientFactory } from '@shi-corp/sdk-url-shortener';

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

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

/**
 * Configured client for URL Shortener that can make authenticated web requests against backend.
 *
 * The third param, the scope is the `Application ID` of the `End User Login` app registration.
 */
const urlShortenerClient = urlShortenerClientFactory(credential, baseUrl, ['b9689d4e-0036-4f2f-8430-07adedb9ae7c/.default']);

/** List of available redirect entries. */
const results = await urlShortenerClient.api.redirect.get();

// Check if list is not empty
if (results?.length > 0) {
    // 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:3004') : new URL('https://custom-host.example.com/Ballance/Instance1/');

/** Configured instance of the URL Shortener client. */
const customConfiguredClient = urlShortenerClientFactory(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 = urlShortenerClientFactory(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-script generate:Sdk
```

### Building the SDK

To build the SDK for production, run:

```bash
npm run-script 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).