Merge pull request #19 from Software-Hardware-Integration-Lab/pasha-sus-spec

[Feature] Adding URL Shortener application

Author: elliot-huffman

.github/workflows/DeploySpecDocs.yml

@@ -49,7 +49,7 @@ jobs:
           run: |
             DIST_FILE="swagger-ui/dist/swagger-initializer.js"
             # Remove the 'url:' property and insert the 'urls:' array
-            sed -i '/url: /c\    urls: [\n      {\n        "url": "https://raw.githubusercontent.com/Software-Hardware-Integration-Lab/OpenAPI/refs/heads/main/specs/Data-Gateway.json",\n        "name": "Data Gateway"\n      },\n      {\n        "url": "https://raw.githubusercontent.com/Software-Hardware-Integration-Lab/OpenAPI/refs/heads/main/specs/SHIELD.json",\n        "name": "SHIELD"\n      }\n    ],' "$DIST_FILE"
+            sed -i '/url: /c\    urls: [\n{\n"url": "https://raw.githubusercontent.com/Software-Hardware-Integration-Lab/OpenAPI/refs/heads/main/specs/Data-Gateway.json",\n"name": "Data Gateway"\n},\n{\n"url": "https://raw.githubusercontent.com/Software-Hardware-Integration-Lab/OpenAPI/refs/heads/main/specs/SHIELD.json",\n"name": "SHIELD"\n}\n{\n"url": "https://raw.githubusercontent.com/Software-Hardware-Integration-Lab/OpenAPI/refs/heads/main/specs/Url-Shortener.json",\n"name": "Data Gateway"\n}\n],' "$DIST_FILE"
 
         # Uploads the built artifact to github pages
         - name: Upload Artifact

OpenAPI.code-workspace

@@ -12,6 +12,10 @@
 			"name": "SHIELD",
 			"path": "src/shield"
 		},
+		{
+			"name": "URL Shortener",
+			"path": "src/urlShortener"
+		},
 		{
 			"name": "GitHub Actions",
 			"path": ".github/workflows"

specs/Url-Shortener.json

@@ -0,0 +1,9 @@
+# Ignore TypeScript source files while allowing library type descriptions
+*.ts
+!*.d.ts
+
+# Ignore the TypeScript config
+tsconfig.json
+
+# Ignore the generated SDK source code
+/sdk/

src/urlShortener/TypeScript/.npmignore

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 SHI International Corp.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

src/urlShortener/TypeScript/LICENSE

@@ -0,0 +1,109 @@
+# 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).

src/urlShortener/TypeScript/README.md

@@ -0,0 +1,40 @@
+import { assert, assertGuardEquals } from 'typia';
+import { AzureIdentityAuthenticationProvider } from "@microsoft/kiota-authentication-azure";
+import { FetchRequestAdapter } from "@microsoft/kiota-http-fetchlibrary";
+import type { TokenCredential } from "@azure/core-auth";
+import { createUrlShortenerClient } from "./sdk/urlShortenerClient.js";
+
+// Export all of the SDK's types
+export type * from './sdk/models/index.js';
+
+/**
+ * Function that initializes the URL Shortener SDK.
+ * @param credential Configured authentication session from Entra ID.
+ * @param baseUrl Root of the URL that should have endpoints appended to it by the query building system.
+ * @param scopeList Where each array item is a different Entra ID standard scope to request on token retrieval. E.g. `['313f3894-325a-4aae-ba2b-bbdfdc1f063b/.default']`
+ * @returns Configured API client that is able to make requests against the specified URL Shortener instance.
+ */
+export function urlShortenerClientFactory(credential: TokenCredential, baseUrl: URL, scopeList: string[]) {
+    // #region Input Validation
+    assert(credential);
+
+    assertGuardEquals(baseUrl);
+
+    assertGuardEquals(scopeList);
+    // #endregion Input Validation
+
+    /** List of hosts that are allowed when making API calls, this is used to prevent token leaks to threat actors. */
+    const allowedHostList = new Set([baseUrl.host]);
+
+    /** Authentication system that will be used to configure the SDK client. */
+    const authProvider = new AzureIdentityAuthenticationProvider(credential, scopeList, void 0, allowedHostList);
+
+    /** Instance of the URL Shortener SDK client initialization configuration. */
+    const urlShortenerAdapter = new FetchRequestAdapter(authProvider);
+
+    // Set the base URL to be what is provided, since the host name is unique every deployment
+    urlShortenerAdapter.baseUrl = baseUrl.href.endsWith('/') ? baseUrl.href.substring(0, baseUrl.href.length - 1) : baseUrl.href;
+
+    /** Instance of the API client that can be used for  URL Shortener access. */
+    return createUrlShortenerClient(urlShortenerAdapter);
+}