@twin.org/api-service 0.0.3-next.9 → 0.9.0

package/docs/examples.md

@@ -1 +1,74 @@
-# @twin.org/api-service - Examples
+# Service Examples
+
+These snippets demonstrate how to configure service-level URL generation and expose operational information for monitoring.
+
+## InformationService
+
+```typescript
+import { InformationService } from '@twin.org/api-service';
+
+const infoService = new InformationService({
+  config: {
+    serverInfo: {
+      name: 'Twin API',
+      version: '1.2.0'
+    }
+  }
+});
+
+await infoService.start();
+console.log(infoService.className()); // InformationService
+
+const root = await infoService.root();
+const info = await infoService.info();
+const favicon = await infoService.favicon();
+
+console.log(root); // Twin API - 1.2.0
+console.log(info.version); // 1.2.0
+console.log((favicon?.byteLength ?? 0) > 0); // true
+```
+
+```typescript
+import { InformationService } from '@twin.org/api-service';
+
+const infoService = new InformationService({
+  config: {
+    serverInfo: {
+      name: 'Twin API',
+      version: '1.2.0'
+    }
+  }
+});
+
+const spec = await infoService.spec();
+const live = await infoService.livez();
+const health = await infoService.health();
+
+await infoService.setComponentHealth('queue', 'ok');
+await infoService.removeComponentHealth('queue');
+
+console.log(typeof spec); // undefined
+console.log(live); // true
+console.log(health.status); // ok
+```
+
+## HostingService
+
+```typescript
+import { HostingService } from '@twin.org/api-service';
+
+const hostingService = new HostingService({
+  config: {
+    localOrigin: 'http://localhost:3000',
+    publicOrigin: 'https://api.example.org'
+  }
+});
+
+console.log(hostingService.className()); // HostingService
+
+const publicOrigin = await hostingService.getPublicOrigin('http://localhost:3000/users');
+const usersUrl = await hostingService.buildPublicUrl('http://localhost:3000/users');
+
+console.log(publicOrigin); // https://api.example.org
+console.log(usersUrl); // https://api.example.org/users
+```

package/docs/reference/classes/HealthService.md

@@ -0,0 +1,123 @@
+# Class: HealthService
+
+The health service for the server.
+
+## Implements
+
+- `IHealthComponent`
+
+## Constructors
+
+### Constructor
+
+> **new HealthService**(`options?`): `HealthService`
+
+Create a new instance of HealthService.
+
+#### Parameters
+
+##### options?
+
+[`IHealthServiceConstructorOptions`](../interfaces/IHealthServiceConstructorOptions.md)
+
+The constructor options.
+
+#### Returns
+
+`HealthService`
+
+## Properties
+
+### CLASS\_NAME {#class_name}
+
+> `readonly` `static` **CLASS\_NAME**: `string`
+
+Runtime name for the class.
+
+## Methods
+
+### className() {#classname}
+
+> **className**(): `string`
+
+Returns the class name of the component.
+
+#### Returns
+
+`string`
+
+The class name of the component.
+
+#### Implementation of
+
+`IHealthComponent.className`
+
+***
+
+### start() {#start}
+
+> **start**(`nodeLoggingComponentType?`): `Promise`\<`void`\>
+
+The component needs to be started when the node is initialized.
+
+#### Parameters
+
+##### nodeLoggingComponentType?
+
+`string`
+
+The node logging component type.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the initial health check timer has been scheduled.
+
+#### Implementation of
+
+`IHealthComponent.start`
+
+***
+
+### stop() {#stop}
+
+> **stop**(`nodeLoggingComponentType?`): `Promise`\<`void`\>
+
+The component needs to be stopped when the node is closed.
+
+#### Parameters
+
+##### nodeLoggingComponentType?
+
+`string`
+
+The node logging component type.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the health check timer has been cancelled.
+
+#### Implementation of
+
+`IHealthComponent.stop`
+
+***
+
+### healthStatus() {#healthstatus}
+
+> **healthStatus**(): `Promise`\<\{ `status`: `HealthStatus`; `components`: `IHealth`[]; \}\>
+
+Get the server health.
+
+#### Returns
+
+`Promise`\<\{ `status`: `HealthStatus`; `components`: `IHealth`[]; \}\>
+
+The service health.
+
+#### Implementation of
+
+`IHealthComponent.healthStatus`

package/docs/reference/classes/InformationService.md

@@ -28,7 +28,7 @@ The options to create the service.
 
 ## Properties
 
-### CLASS\_NAME
+### CLASS\_NAME {#class_name}
 
 > `readonly` `static` **CLASS\_NAME**: `string`
 
@@ -36,7 +36,7 @@ Runtime name for the class.
 
 ## Methods
 
-### className()
+### className() {#classname}
 
 > **className**(): `string`
 
@@ -54,7 +54,7 @@ The class name of the component.
 
 ***
 
-### start()
+### start() {#start}
 
 > **start**(): `Promise`\<`void`\>
 
@@ -64,7 +64,7 @@ The service needs to be started when the application is initialized.
 
 `Promise`\<`void`\>
 
-Nothing.
+A promise that resolves when the OpenAPI spec and favicon have been loaded from disk.
 
 #### Implementation of
 
@@ -72,7 +72,7 @@ Nothing.
 
 ***
 
-### root()
+### root() {#root}
 
 > **root**(): `Promise`\<`string`\>
 
@@ -90,7 +90,7 @@ The root information.
 
 ***
 
-### info()
+### info() {#info}
 
 > **info**(): `Promise`\<`IServerInfo`\>
 
@@ -108,7 +108,7 @@ The service information.
 
 ***
 
-### favicon()
+### favicon() {#favicon}
 
 > **favicon**(): `Promise`\<`Uint8Array`\<`ArrayBufferLike`\> \| `undefined`\>
 
@@ -126,7 +126,7 @@ The favicon.
 
 ***
 
-### spec()
+### spec() {#spec}
 
 > **spec**(): `Promise`\<`unknown`\>
 
@@ -144,17 +144,17 @@ The OpenAPI spec.
 
 ***
 
-### livez()
+### livez() {#livez}
 
-> **livez**(): `Promise`\<`boolean`\>
+> **livez**(): `Promise`\<\{ `status`: `"alive"` \| `"dead"`; \}\>
 
 Is the server live.
 
 #### Returns
 
-`Promise`\<`boolean`\>
+`Promise`\<\{ `status`: `"alive"` \| `"dead"`; \}\>
 
-True if the server is live.
+The liveness status of the server.
 
 #### Implementation of
 
@@ -162,94 +162,18 @@ True if the server is live.
 
 ***
 
-### health()
+### readyz() {#readyz}
 
-> **health**(): `Promise`\<`IHealthInfo`\>
+> **readyz**(): `Promise`\<\{ `status`: `"ready"` \| `"not ready"`; \}\>
 
-Get the server health.
+Is the server ready.
 
 #### Returns
 
-`Promise`\<`IHealthInfo`\>
+`Promise`\<\{ `status`: `"ready"` \| `"not ready"`; \}\>
 
-The service health.
+The readyz status of the server.
 
 #### Implementation of
 
-`IInformationComponent.health`
-
-***
-
-### setComponentHealth()
-
-> **setComponentHealth**(`name`, `status`, `details?`, `tenantId?`): `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.
-
-##### tenantId?
-
-`string`
-
-The tenant id, optional if the health status is not tenant specific.
-
-#### Returns
-
-`Promise`\<`void`\>
-
-Nothing.
-
-#### Implementation of
-
-`IInformationComponent.setComponentHealth`
-
-***
-
-### removeComponentHealth()
-
-> **removeComponentHealth**(`name`, `tenantId?`): `Promise`\<`void`\>
-
-Remove the status of a component.
-
-#### Parameters
-
-##### name
-
-`string`
-
-The component name.
-
-##### tenantId?
-
-`string`
-
-The tenant id, optional if the health status is not tenant specific.
-
-#### Returns
-
-`Promise`\<`void`\>
-
-Nothing.
-
-#### Implementation of
-
-`IInformationComponent.removeComponentHealth`
+`IInformationComponent.readyz`

package/docs/reference/classes/PlatformService.md

@@ -0,0 +1,123 @@
+# Class: PlatformService
+
+Service for performing platform operations.
+
+## Implements
+
+- `IPlatformComponent`
+
+## Constructors
+
+### Constructor
+
+> **new PlatformService**(`options?`): `PlatformService`
+
+Create a new instance of PlatformService.
+
+#### Parameters
+
+##### options?
+
+[`IPlatformServiceConstructorOptions`](../interfaces/IPlatformServiceConstructorOptions.md)
+
+The options for the connector.
+
+#### Returns
+
+`PlatformService`
+
+## Properties
+
+### CLASS\_NAME {#class_name}
+
+> `readonly` `static` **CLASS\_NAME**: `string`
+
+Runtime name for the class.
+
+## Methods
+
+### className() {#classname}
+
+> **className**(): `string`
+
+Returns the class name of the component.
+
+#### Returns
+
+`string`
+
+The class name of the component.
+
+#### Implementation of
+
+`IPlatformComponent.className`
+
+***
+
+### isMultiTenant() {#ismultitenant}
+
+> **isMultiTenant**(): `boolean`
+
+Indicates whether the component is running in a multi-tenant environment.
+
+#### Returns
+
+`boolean`
+
+True if the component is running in a multi-tenant environment, false otherwise.
+
+#### Implementation of
+
+`IPlatformComponent.isMultiTenant`
+
+***
+
+### execute() {#execute}
+
+> **execute**(`method`): `Promise`\<`void`\>
+
+Execute a method, if single tenant will run once, if multi-tenant will run for each tenant.
+
+#### Parameters
+
+##### method
+
+() => `Promise`\<`void`\>
+
+The method to run for each tenant.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the method has been executed for all applicable tenants.
+
+#### Implementation of
+
+`IPlatformComponent.execute`
+
+***
+
+### getLocalOriginContext() {#getlocalorigincontext}
+
+> **getLocalOriginContext**(`url`): `Promise`\<`IContextIds` \| `undefined`\>
+
+Get the local origin context IDs for the given URL.
+
+#### Parameters
+
+##### url
+
+`string`
+
+The URL to check.
+
+#### Returns
+
+`Promise`\<`IContextIds` \| `undefined`\>
+
+A promise that resolves to the context IDs if the URL is a local origin, undefined otherwise.
+
+#### Implementation of
+
+`IPlatformComponent.getLocalOriginContext`

package/docs/reference/functions/generateRestRoutesHealth.md

@@ -0,0 +1,25 @@
+# Function: generateRestRoutesHealth()
+
+> **generateRestRoutesHealth**(`baseRouteName`, `componentName`): `IRestRoute`\<`any`, `any`\>[]
+
+The REST routes for server health.
+
+## 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`\<`any`, `any`\>[]
+
+The generated routes.

package/docs/reference/functions/serverReadyz.md

@@ -0,0 +1,31 @@
+# Function: serverReadyz()
+
+> **serverReadyz**(`httpRequestContext`, `componentName`, `request`): `Promise`\<`IServerReadyzResponse`\>
+
+Get the readyz 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`\<`IServerReadyzResponse`\>
+
+The response object with additional http response properties.

package/docs/reference/index.md

@@ -2,24 +2,33 @@
 
 ## Classes
 
+- [HealthService](classes/HealthService.md)
 - [InformationService](classes/InformationService.md)
+- [PlatformService](classes/PlatformService.md)
 
 ## Interfaces
 
+- [IHealthServiceConfig](interfaces/IHealthServiceConfig.md)
+- [IHealthServiceConstructorOptions](interfaces/IHealthServiceConstructorOptions.md)
 - [IInformationServiceConfig](interfaces/IInformationServiceConfig.md)
 - [IInformationServiceConstructorOptions](interfaces/IInformationServiceConstructorOptions.md)
+- [IPlatformServiceConfig](interfaces/IPlatformServiceConfig.md)
+- [IPlatformServiceConstructorOptions](interfaces/IPlatformServiceConstructorOptions.md)
 
 ## Variables
 
+- [tagsHealth](variables/tagsHealth.md)
 - [tagsInformation](variables/tagsInformation.md)
 - [restEntryPoints](variables/restEntryPoints.md)
 
 ## Functions
 
+- [generateRestRoutesHealth](functions/generateRestRoutesHealth.md)
+- [serverHealth](functions/serverHealth.md)
 - [generateRestRoutesInformation](functions/generateRestRoutesInformation.md)
 - [serverRoot](functions/serverRoot.md)
 - [serverInfo](functions/serverInfo.md)
 - [serverLivez](functions/serverLivez.md)
-- [serverHealth](functions/serverHealth.md)
+- [serverReadyz](functions/serverReadyz.md)
 - [serverFavIcon](functions/serverFavIcon.md)
 - [serverSpec](functions/serverSpec.md)

package/docs/reference/interfaces/IHealthServiceConfig.md

@@ -0,0 +1,32 @@
+# Interface: IHealthServiceConfig
+
+Configuration for the health service.
+
+## Properties
+
+### healthCheckInterval? {#healthcheckinterval}
+
+> `optional` **healthCheckInterval?**: `number`
+
+The interval for checking the health of the components and setting it in the health service.
+
+#### Default
+
+```ts
+60000
+```
+
+***
+
+### initialInterval? {#initialinterval}
+
+> `optional` **initialInterval?**: `number`
+
+The initial interval for checking the health of the components and setting it in the health service.
+This is used to check the health of the components immediately after the service is started.
+
+#### Default
+
+```ts
+2000
+```

package/docs/reference/interfaces/IHealthServiceConstructorOptions.md

@@ -0,0 +1,11 @@
+# Interface: IHealthServiceConstructorOptions
+
+Options for the HealthService constructor.
+
+## Properties
+
+### config? {#config}
+
+> `optional` **config?**: [`IHealthServiceConfig`](IHealthServiceConfig.md)
+
+The configuration for the service.

package/docs/reference/interfaces/IInformationServiceConfig.md

@@ -4,7 +4,7 @@ Configuration for the information service.
 
 ## Properties
 
-### serverInfo
+### serverInfo {#serverinfo}
 
 > **serverInfo**: `IServerInfo`
 
@@ -12,16 +12,16 @@ The server information.
 
 ***
 
-### openApiSpecPath?
+### openApiSpecPath? {#openapispecpath}
 
-> `optional` **openApiSpecPath**: `string`
+> `optional` **openApiSpecPath?**: `string`
 
 The path to the OpenAPI Spec.
 
 ***
 
-### favIconPath?
+### favIconPath? {#faviconpath}
 
-> `optional` **favIconPath**: `string`
+> `optional` **favIconPath?**: `string`
 
 The path to the favicon.

package/docs/reference/interfaces/IInformationServiceConstructorOptions.md

@@ -4,7 +4,7 @@ Options for the InformationService constructor.
 
 ## Properties
 
-### config
+### config {#config}
 
 > **config**: [`IInformationServiceConfig`](IInformationServiceConfig.md)
 

package/docs/reference/interfaces/IPlatformServiceConfig.md

@@ -0,0 +1,17 @@
+# Interface: IPlatformServiceConfig
+
+Configuration for the platform service
+
+## Properties
+
+### isMultiTenant? {#ismultitenant}
+
+> `optional` **isMultiTenant?**: `boolean`
+
+Indicates whether the service is running in a multi-tenant environment.
+
+#### Default
+
+```ts
+false
+```