@twin.org/api-service 0.0.1-next.2

package/dist/esm/index.mjs

@@ -0,0 +1,347 @@
+import { ComponentFactory, Is } from '@twin.org/core';
+import { HttpStatusCode } from '@twin.org/web';
+import { readFile } from 'node:fs/promises';
+
+/**
+ * The tag to associate with the routes.
+ */
+const tagsInformation = [
+    {
+        name: "Info",
+        description: "Information endpoints for the REST server."
+    }
+];
+/**
+ * The REST routes for server information.
+ * @param baseRouteName Prefix to prepend to the paths.
+ * @param componentName The name of the component to use in the routes stored in the ComponentFactory.
+ * @returns The generated routes.
+ */
+function generateRestRoutesInformation(baseRouteName, componentName) {
+    const rootRoute = {
+        operationId: "serverRoot",
+        summary: "Get the root blank page",
+        tag: tagsInformation[0].name,
+        method: "GET",
+        path: `${baseRouteName}/`,
+        handler: async () => ({}),
+        responseType: [
+            {
+                type: "INoContentResponse"
+            }
+        ],
+        excludeFromSpec: true,
+        skipAuth: true
+    };
+    const informationRoute = {
+        operationId: "serverInformation",
+        summary: "Get the information for the server",
+        tag: tagsInformation[0].name,
+        method: "GET",
+        path: `${baseRouteName}/info`,
+        handler: async (httpRequestContext, request) => serverInfo(httpRequestContext, componentName),
+        responseType: [
+            {
+                type: "IServerInfoResponse",
+                examples: [
+                    {
+                        id: "informationResponse",
+                        description: "The response for the information request.",
+                        response: {
+                            body: {
+                                name: "API Server",
+                                version: "1.0.0"
+                            }
+                        }
+                    }
+                ]
+            }
+        ],
+        skipAuth: true
+    };
+    const healthRoute = {
+        operationId: "serverHealth",
+        summary: "Get the health for the server",
+        tag: tagsInformation[0].name,
+        method: "GET",
+        path: `${baseRouteName}/health`,
+        handler: async (httpRequestContext, request) => serverHealth(httpRequestContext, componentName),
+        responseType: [
+            {
+                type: "IServerHealthResponse",
+                examples: [
+                    {
+                        id: "healthResponseOK",
+                        description: "The response for the health request.",
+                        response: {
+                            body: {
+                                status: "ok",
+                                components: [
+                                    {
+                                        name: "Database",
+                                        status: "ok"
+                                    },
+                                    {
+                                        name: "Storage",
+                                        status: "ok"
+                                    }
+                                ]
+                            }
+                        }
+                    },
+                    {
+                        id: "healthResponseWarning",
+                        description: "The response for the health request with warnings.",
+                        response: {
+                            body: {
+                                status: "warning",
+                                components: [
+                                    {
+                                        name: "Database",
+                                        status: "warning",
+                                        details: "The database is running slow."
+                                    },
+                                    {
+                                        name: "Storage",
+                                        status: "ok"
+                                    }
+                                ]
+                            }
+                        }
+                    },
+                    {
+                        id: "healthResponseError",
+                        description: "The response for the health request with errors.",
+                        response: {
+                            body: {
+                                status: "error",
+                                components: [
+                                    {
+                                        name: "Database",
+                                        status: "ok"
+                                    },
+                                    {
+                                        name: "Storage",
+                                        status: "error",
+                                        details: "The storage is full."
+                                    }
+                                ]
+                            }
+                        }
+                    }
+                ]
+            }
+        ],
+        skipAuth: true
+    };
+    const specRoute = {
+        operationId: "serverSpec",
+        summary: "Get the OpenAPI specification for the endpoints",
+        tag: tagsInformation[0].name,
+        method: "GET",
+        path: `${baseRouteName}/spec`,
+        handler: async (httpRequestContext, request) => serverSpec(httpRequestContext, componentName),
+        responseType: [
+            {
+                type: "IServerSpecResponse",
+                examples: [
+                    {
+                        id: "specResponse",
+                        description: "The response for the spec request.",
+                        response: {
+                            body: {
+                                openapi: "3.1.0",
+                                info: {},
+                                paths: {}
+                            }
+                        }
+                    }
+                ]
+            }
+        ],
+        skipAuth: true
+    };
+    return [rootRoute, informationRoute, healthRoute, specRoute];
+}
+/**
+ * Get the information for the server.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+async function serverInfo(httpRequestContext, componentName, request) {
+    const component = ComponentFactory.get(componentName);
+    return {
+        body: await component.info()
+    };
+}
+/**
+ * Get the health for the server.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+async function serverHealth(httpRequestContext, componentName, request) {
+    const component = ComponentFactory.get(componentName);
+    return {
+        body: await component.health()
+    };
+}
+/**
+ * Get the spec for the server.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+async function serverSpec(httpRequestContext, componentName, request) {
+    const component = ComponentFactory.get(componentName);
+    const spec = await component.spec();
+    if (Is.objectValue(spec)) {
+        return {
+            body: spec
+        };
+    }
+    return {
+        statusCode: HttpStatusCode.notFound
+    };
+}
+
+const restEntryPoints = [
+    {
+        name: "information",
+        defaultBaseRoute: "",
+        tags: tagsInformation,
+        generateRoutes: generateRestRoutesInformation
+    }
+];
+
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * The information service for the server.
+ */
+class InformationService {
+    /**
+     * Runtime name for the class.
+     */
+    CLASS_NAME = "InformationService";
+    /**
+     * The server information.
+     * @internal
+     */
+    _serverInfo;
+    /**
+     * The server health.
+     * @internal
+     */
+    _healthInfo;
+    /**
+     * The path to the OpenAPI Spec.
+     * @internal
+     */
+    _openApiSpecPath;
+    /**
+     * The OpenAPI spec.
+     * @internal
+     */
+    _openApiSpec;
+    /**
+     * Create a new instance of InformationService.
+     * @param serverInfo The server information.
+     * @param openApiSpecPath The path to the spec file.
+     */
+    constructor(serverInfo, openApiSpecPath) {
+        this._serverInfo = serverInfo;
+        this._healthInfo = {
+            status: "ok"
+        };
+        this._openApiSpecPath = openApiSpecPath;
+    }
+    /**
+     * The service needs to be started when the application is initialized.
+     * @returns Nothing.
+     */
+    async start() {
+        const filename = this._openApiSpecPath;
+        if (Is.stringValue(filename)) {
+            const contentBuffer = await readFile(filename, "utf8");
+            this._openApiSpec = JSON.parse(contentBuffer);
+        }
+    }
+    /**
+     * Get the server information.
+     * @returns The service information.
+     */
+    async info() {
+        return this._serverInfo;
+    }
+    /**
+     * Get the OpenAPI spec.
+     * @returns The OpenAPI spec.
+     */
+    async spec() {
+        return this._openApiSpec;
+    }
+    /**
+     * Get the server health.
+     * @returns The service health.
+     */
+    async health() {
+        let errorCount = 0;
+        let warningCount = 0;
+        if (Is.arrayValue(this._healthInfo.components)) {
+            errorCount = this._healthInfo.components.filter(c => c.status === "error").length;
+            warningCount = this._healthInfo.components.filter(c => c.status === "warning").length;
+        }
+        if (errorCount > 0) {
+            this._healthInfo.status = "error";
+        }
+        else if (warningCount > 0) {
+            this._healthInfo.status = "warning";
+        }
+        else {
+            this._healthInfo.status = "ok";
+        }
+        return this._healthInfo;
+    }
+    /**
+     * Set the status of a component.
+     * @param name The component name.
+     * @param status The status of the component.
+     * @param details The details for the status.
+     * @returns Nothing.
+     */
+    async setComponentHealth(name, status, details) {
+        const component = this._healthInfo.components?.find(c => c.name === name);
+        if (Is.undefined(component)) {
+            this._healthInfo.components ??= [];
+            this._healthInfo.components.push({
+                name,
+                status,
+                details
+            });
+        }
+        else {
+            component.status = status;
+            component.details = details;
+        }
+    }
+    /**
+     * Remove the status of a component.
+     * @param name The component name.
+     * @returns Nothing.
+     */
+    async removeComponentHealth(name) {
+        if (Is.arrayValue(this._healthInfo.components)) {
+            const componentIndex = this._healthInfo.components.findIndex(c => c.name === name);
+            if (componentIndex >= 0) {
+                this._healthInfo.components.splice(componentIndex, 1);
+            }
+        }
+    }
+}
+
+export { InformationService, generateRestRoutesInformation, restEntryPoints, serverHealth, serverInfo, serverSpec, tagsInformation };

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./informationRoutes";
+export * from "./restEntryPoints";
+export * from "./informationService";

package/dist/types/informationRoutes.d.ts

@@ -0,0 +1,36 @@
+import type { IHttpRequestContext, INoContentRequest, IRestRoute, IServerHealthResponse, IServerInfoResponse, IServerSpecResponse, ITag } from "@twin.org/api-models";
+/**
+ * The tag to associate with the routes.
+ */
+export declare const tagsInformation: ITag[];
+/**
+ * The REST routes for server information.
+ * @param baseRouteName Prefix to prepend to the paths.
+ * @param componentName The name of the component to use in the routes stored in the ComponentFactory.
+ * @returns The generated routes.
+ */
+export declare function generateRestRoutesInformation(baseRouteName: string, componentName: string): IRestRoute[];
+/**
+ * Get the information for the server.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function serverInfo(httpRequestContext: IHttpRequestContext, componentName: string, request: INoContentRequest): Promise<IServerInfoResponse>;
+/**
+ * Get the health for the server.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function serverHealth(httpRequestContext: IHttpRequestContext, componentName: string, request: INoContentRequest): Promise<IServerHealthResponse>;
+/**
+ * Get the spec for the server.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function serverSpec(httpRequestContext: IHttpRequestContext, componentName: string, request: INoContentRequest): Promise<IServerSpecResponse>;

package/dist/types/informationService.d.ts

@@ -0,0 +1,50 @@
+import type { HealthStatus, IHealthInfo, IInformationComponent, IServerInfo } from "@twin.org/api-models";
+/**
+ * The information service for the server.
+ */
+export declare class InformationService implements IInformationComponent {
+    /**
+     * Runtime name for the class.
+     */
+    readonly CLASS_NAME: string;
+    /**
+     * Create a new instance of InformationService.
+     * @param serverInfo The server information.
+     * @param openApiSpecPath The path to the spec file.
+     */
+    constructor(serverInfo: IServerInfo, openApiSpecPath?: string);
+    /**
+     * The service needs to be started when the application is initialized.
+     * @returns Nothing.
+     */
+    start(): Promise<void>;
+    /**
+     * Get the server information.
+     * @returns The service information.
+     */
+    info(): Promise<IServerInfo>;
+    /**
+     * Get the OpenAPI spec.
+     * @returns The OpenAPI spec.
+     */
+    spec(): Promise<unknown>;
+    /**
+     * Get the server health.
+     * @returns The service health.
+     */
+    health(): Promise<IHealthInfo>;
+    /**
+     * Set the status of a component.
+     * @param name The component name.
+     * @param status The status of the component.
+     * @param details The details for the status.
+     * @returns Nothing.
+     */
+    setComponentHealth(name: string, status: HealthStatus, details?: string): Promise<void>;
+    /**
+     * Remove the status of a component.
+     * @param name The component name.
+     * @returns Nothing.
+     */
+    removeComponentHealth(name: string): Promise<void>;
+}

package/dist/types/restEntryPoints.d.ts

@@ -0,0 +1,2 @@
+import type { IRestRouteEntryPoint } from "@twin.org/api-models";
+export declare const restEntryPoints: IRestRouteEntryPoint[];

package/docs/changelog.md

@@ -0,0 +1,5 @@
+# @twin.org/api-service - Changelog
+
+## v0.0.1-next.2
+
+- Initial Release

package/docs/examples.md

@@ -0,0 +1 @@
+# @twin.org/api-service - Examples

package/docs/reference/classes/InformationService.md

@@ -0,0 +1,169 @@
+# Class: InformationService
+
+The information service for the server.
+
+## Implements
+
+- `IInformationComponent`
+
+## Constructors
+
+### new InformationService()
+
+> **new InformationService**(`serverInfo`, `openApiSpecPath`?): [`InformationService`](InformationService.md)
+
+Create a new instance of InformationService.
+
+#### Parameters
+
+• **serverInfo**: `IServerInfo`
+
+The server information.
+
+• **openApiSpecPath?**: `string`
+
+The path to the spec file.
+
+#### Returns
+
+[`InformationService`](InformationService.md)
+
+## Properties
+
+### CLASS\_NAME
+
+> `readonly` **CLASS\_NAME**: `string`
+
+Runtime name for the class.
+
+#### Implementation of
+
+`IInformationComponent.CLASS_NAME`
+
+## Methods
+
+### start()
+
+> **start**(): `Promise`\<`void`\>
+
+The service needs to be started when the application is initialized.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.
+
+#### Implementation of
+
+`IInformationComponent.start`
+
+***
+
+### info()
+
+> **info**(): `Promise`\<`IServerInfo`\>
+
+Get the server information.
+
+#### Returns
+
+`Promise`\<`IServerInfo`\>
+
+The service information.
+
+#### Implementation of
+
+`IInformationComponent.info`
+
+***
+
+### spec()
+
+> **spec**(): `Promise`\<`unknown`\>
+
+Get the OpenAPI spec.
+
+#### Returns
+
+`Promise`\<`unknown`\>
+
+The OpenAPI spec.
+
+#### Implementation of
+
+`IInformationComponent.spec`
+
+***
+
+### health()
+
+> **health**(): `Promise`\<`IHealthInfo`\>
+
+Get the server health.
+
+#### Returns
+
+`Promise`\<`IHealthInfo`\>
+
+The service health.
+
+#### Implementation of
+
+`IInformationComponent.health`
+
+***
+
+### setComponentHealth()
+
+> **setComponentHealth**(`name`, `status`, `details`?): `Promise`\<`void`\>
+
+Set the status of a component.
+
+#### Parameters
+
+• **name**: `string`
+
+The component name.
+
+• **status**: `HealthStatus`
+
+The status of the component.
+
+• **details?**: `string`
+
+The details for the status.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.
+
+#### Implementation of
+
+`IInformationComponent.setComponentHealth`
+
+***
+
+### removeComponentHealth()
+
+> **removeComponentHealth**(`name`): `Promise`\<`void`\>
+
+Remove the status of a component.
+
+#### Parameters
+
+• **name**: `string`
+
+The component name.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.
+
+#### Implementation of
+
+`IInformationComponent.removeComponentHealth`

package/docs/reference/functions/generateRestRoutesInformation.md

@@ -0,0 +1,21 @@
+# Function: generateRestRoutesInformation()
+
+> **generateRestRoutesInformation**(`baseRouteName`, `componentName`): `IRestRoute`[]
+
+The REST routes for server information.
+
+## Parameters
+
+• **baseRouteName**: `string`
+
+Prefix to prepend to the paths.
+
+• **componentName**: `string`
+
+The name of the component to use in the routes stored in the ComponentFactory.
+
+## Returns
+
+`IRestRoute`[]
+
+The generated routes.

package/docs/reference/functions/serverHealth.md

@@ -0,0 +1,25 @@
+# Function: serverHealth()
+
+> **serverHealth**(`httpRequestContext`, `componentName`, `request`): `Promise`\<`IServerHealthResponse`\>
+
+Get the health for the server.
+
+## Parameters
+
+• **httpRequestContext**: `IHttpRequestContext`
+
+The request context for the API.
+
+• **componentName**: `string`
+
+The name of the component to use in the routes.
+
+• **request**: `INoContentRequest`
+
+The request.
+
+## Returns
+
+`Promise`\<`IServerHealthResponse`\>
+
+The response object with additional http response properties.

package/docs/reference/functions/serverInfo.md

@@ -0,0 +1,25 @@
+# Function: serverInfo()
+
+> **serverInfo**(`httpRequestContext`, `componentName`, `request`): `Promise`\<`IServerInfoResponse`\>
+
+Get the information for the server.
+
+## Parameters
+
+• **httpRequestContext**: `IHttpRequestContext`
+
+The request context for the API.
+
+• **componentName**: `string`
+
+The name of the component to use in the routes.
+
+• **request**: `INoContentRequest`
+
+The request.
+
+## Returns
+
+`Promise`\<`IServerInfoResponse`\>
+
+The response object with additional http response properties.