@twin.org/api-service 0.0.3-next.4 → 0.0.3-next.40

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`\>
+
+Nothing.
+
+#### 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`\>
+
+Nothing.
+
+#### 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/HostingService.md

@@ -0,0 +1,131 @@
+# Class: HostingService
+
+The hosting service for the server.
+
+## Implements
+
+- `IHostingComponent`
+
+## Constructors
+
+### Constructor
+
+> **new HostingService**(`options`): `HostingService`
+
+Create a new instance of HostingService.
+
+#### Parameters
+
+##### options
+
+[`IHostingServiceConstructorOptions`](../interfaces/IHostingServiceConstructorOptions.md)
+
+The options to create the service.
+
+#### Returns
+
+`HostingService`
+
+## 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
+
+`IHostingComponent.className`
+
+***
+
+### getPublicOrigin() {#getpublicorigin}
+
+> **getPublicOrigin**(`serverRequestUrl?`): `Promise`\<`string`\>
+
+Get the public origin for the hosting.
+
+#### Parameters
+
+##### serverRequestUrl?
+
+`string`
+
+The url of the current server request if there is one.
+
+#### Returns
+
+`Promise`\<`string`\>
+
+The public origin.
+
+#### Implementation of
+
+`IHostingComponent.getPublicOrigin`
+
+***
+
+### getTenantOrigin() {#gettenantorigin}
+
+> **getTenantOrigin**(`tenantId`): `Promise`\<`string` \| `undefined`\>
+
+Get the public origin for the tenant if one exists.
+
+#### Parameters
+
+##### tenantId
+
+`string`
+
+The tenant identifier.
+
+#### Returns
+
+`Promise`\<`string` \| `undefined`\>
+
+The public origin for the tenant.
+
+#### Implementation of
+
+`IHostingComponent.getTenantOrigin`
+
+***
+
+### buildPublicUrl() {#buildpublicurl}
+
+> **buildPublicUrl**(`url`): `Promise`\<`string`\>
+
+Build a public url based on the public origin and the url provided.
+
+#### Parameters
+
+##### url
+
+`string`
+
+The url to build upon the public origin.
+
+#### Returns
+
+`Promise`\<`string`\>
+
+The full url based on the public origin.
+
+#### Implementation of
+
+`IHostingComponent.buildPublicUrl`

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`\>
 
@@ -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,82 +144,36 @@ The OpenAPI spec.
 
 ***
 
-### health()
+### livez() {#livez}
 
-> **health**(): `Promise`\<`IHealthInfo`\>
+> **livez**(): `Promise`\<\{ `status`: `"alive"` \| `"dead"`; \}\>
 
-Get the server health.
+Is the server live.
 
 #### Returns
 
-`Promise`\<`IHealthInfo`\>
+`Promise`\<\{ `status`: `"alive"` \| `"dead"`; \}\>
 
-The service health.
+True if the server is live.
 
 #### Implementation of
 
-`IInformationComponent.health`
+`IInformationComponent.livez`
 
 ***
 
-### setComponentHealth()
+### readyz() {#readyz}
 
-> **setComponentHealth**(`name`, `status`, `details?`): `Promise`\<`void`\>
+> **readyz**(): `Promise`\<\{ `status`: `"ready"` \| `"not ready"`; \}\>
 
-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.
+Is the server ready.
 
 #### Returns
 
-`Promise`\<`void`\>
-
-Nothing.
-
-#### Implementation of
+`Promise`\<\{ `status`: `"ready"` \| `"not ready"`; \}\>
 
-`IInformationComponent.setComponentHealth`
-
-***
-
-### removeComponentHealth()
-
-> **removeComponentHealth**(`name`): `Promise`\<`void`\>
-
-Remove the status of a component.
-
-#### Parameters
-
-##### name
-
-`string`
-
-The component name.
-
-#### Returns
-
-`Promise`\<`void`\>
-
-Nothing.
+The readyz status of the server.
 
 #### Implementation of
 
-`IInformationComponent.removeComponentHealth`
+`IInformationComponent.readyz`