@twin.org/api-service 0.0.3-next.2 → 0.0.3-next.21

package/docs/changelog.md

@@ -1,4 +1,287 @@
-# @twin.org/api-service - Changelog
+# Changelog
+
+## [0.0.3-next.21](https://github.com/twinfoundation/api/compare/api-service-v0.0.3-next.20...api-service-v0.0.3-next.21) (2026-03-11)
+
+
+### Miscellaneous Chores
+
+* **api-service:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/api-models bumped from 0.0.3-next.20 to 0.0.3-next.21
+
+## [0.0.3-next.20](https://github.com/twinfoundation/api/compare/api-service-v0.0.3-next.19...api-service-v0.0.3-next.20) (2026-02-09)
+
+
+### Miscellaneous Chores
+
+* **api-service:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/api-models bumped from 0.0.3-next.19 to 0.0.3-next.20
+
+## [0.0.3-next.19](https://github.com/twinfoundation/api/compare/api-service-v0.0.3-next.18...api-service-v0.0.3-next.19) (2026-02-06)
+
+
+### Miscellaneous Chores
+
+* **api-service:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/api-models bumped from 0.0.3-next.18 to 0.0.3-next.19
+
+## [0.0.3-next.18](https://github.com/twinfoundation/api/compare/api-service-v0.0.3-next.17...api-service-v0.0.3-next.18) (2026-02-04)
+
+
+### Miscellaneous Chores
+
+* **api-service:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/api-models bumped from 0.0.3-next.17 to 0.0.3-next.18
+
+## [0.0.3-next.17](https://github.com/twinfoundation/api/compare/api-service-v0.0.3-next.16...api-service-v0.0.3-next.17) (2026-01-26)
+
+
+### Features
+
+* update public origin building ([6c8e042](https://github.com/twinfoundation/api/commit/6c8e0422d9ddbed42a843e1c23498c99977b2fc7))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/api-models bumped from 0.0.3-next.16 to 0.0.3-next.17
+
+## [0.0.3-next.16](https://github.com/twinfoundation/api/compare/api-service-v0.0.3-next.15...api-service-v0.0.3-next.16) (2026-01-26)
+
+
+### Features
+
+* public base url ([#70](https://github.com/twinfoundation/api/issues/70)) ([5b958cd](https://github.com/twinfoundation/api/commit/5b958cd91e8a38cdae2835ff5f2356c7e48d37c3))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/api-models bumped from 0.0.3-next.15 to 0.0.3-next.16
+
+## [0.0.3-next.15](https://github.com/twinfoundation/api/compare/api-service-v0.0.3-next.14...api-service-v0.0.3-next.15) (2026-01-22)
+
+
+### Miscellaneous Chores
+
+* **api-service:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/api-models bumped from 0.0.3-next.14 to 0.0.3-next.15
+
+## [0.0.3-next.14](https://github.com/twinfoundation/api/compare/api-service-v0.0.3-next.13...api-service-v0.0.3-next.14) (2026-01-20)
+
+
+### Miscellaneous Chores
+
+* **api-service:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/api-models bumped from 0.0.3-next.13 to 0.0.3-next.14
+
+## [0.0.3-next.13](https://github.com/twinfoundation/api/compare/api-service-v0.0.3-next.12...api-service-v0.0.3-next.13) (2026-01-19)
+
+
+### Miscellaneous Chores
+
+* **api-service:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/api-models bumped from 0.0.3-next.12 to 0.0.3-next.13
+
+## [0.0.3-next.12](https://github.com/twinfoundation/api/compare/api-service-v0.0.3-next.11...api-service-v0.0.3-next.12) (2026-01-12)
+
+
+### Miscellaneous Chores
+
+* **api-service:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/api-models bumped from 0.0.3-next.11 to 0.0.3-next.12
+
+## [0.0.3-next.11](https://github.com/twinfoundation/api/compare/api-service-v0.0.3-next.10...api-service-v0.0.3-next.11) (2026-01-08)
+
+
+### Miscellaneous Chores
+
+* **api-service:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/api-models bumped from 0.0.3-next.10 to 0.0.3-next.11
+
+## [0.0.3-next.10](https://github.com/twinfoundation/api/compare/api-service-v0.0.3-next.9...api-service-v0.0.3-next.10) (2026-01-05)
+
+
+### Miscellaneous Chores
+
+* **api-service:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/api-models bumped from 0.0.3-next.9 to 0.0.3-next.10
+
+## [0.0.3-next.9](https://github.com/twinfoundation/api/compare/api-service-v0.0.3-next.8...api-service-v0.0.3-next.9) (2026-01-05)
+
+
+### Features
+
+* add context id features ([#42](https://github.com/twinfoundation/api/issues/42)) ([0186055](https://github.com/twinfoundation/api/commit/0186055c48afde842a4254b4df9ac9249c40fe40))
+* add livez endpoint ([#57](https://github.com/twinfoundation/api/issues/57)) ([ef007db](https://github.com/twinfoundation/api/commit/ef007db8201736dd3053211f849ffd03baaa485e))
+* add root, favicon routes ([71da1c3](https://github.com/twinfoundation/api/commit/71da1c3a93c349588aff7084d1d8d6a29a277da8))
+* add validate-locales ([cdba610](https://github.com/twinfoundation/api/commit/cdba610a0acb5022d2e3ce729732e6646a297e5e))
+* eslint migration to flat config ([0dd5820](https://github.com/twinfoundation/api/commit/0dd5820e3af97350fd08b8d226f4a6c1a9246805))
+* remove unused namespace ([08478f2](https://github.com/twinfoundation/api/commit/08478f27efda9beb0271fdb22f6972e918361965))
+* update dependencies ([1171dc4](https://github.com/twinfoundation/api/commit/1171dc416a9481737f6a640e3cf30145768f37e9))
+* update framework core ([d8eebf2](https://github.com/twinfoundation/api/commit/d8eebf267fa2a0abaa84e58590496e9d20490cfa))
+* update IComponent signatures ([915ce37](https://github.com/twinfoundation/api/commit/915ce37712326ab4aa6869c350eabaa4622e8430))
+* use shared store mechanism ([#19](https://github.com/twinfoundation/api/issues/19)) ([32116df](https://github.com/twinfoundation/api/commit/32116df3b4380a30137f5056f242a5c99afa2df9))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/api-models bumped from 0.0.3-next.8 to 0.0.3-next.9
+
+## [0.0.3-next.8](https://github.com/twinfoundation/api/compare/api-service-v0.0.3-next.7...api-service-v0.0.3-next.8) (2025-12-17)
+
+
+### Miscellaneous Chores
+
+* **api-service:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/api-models bumped from 0.0.3-next.7 to 0.0.3-next.8
+
+## [0.0.3-next.7](https://github.com/twinfoundation/api/compare/api-service-v0.0.3-next.6...api-service-v0.0.3-next.7) (2025-11-26)
+
+
+### Miscellaneous Chores
+
+* **api-service:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/api-models bumped from 0.0.3-next.6 to 0.0.3-next.7
+
+## [0.0.3-next.6](https://github.com/twinfoundation/api/compare/api-service-v0.0.3-next.5...api-service-v0.0.3-next.6) (2025-11-20)
+
+
+### Miscellaneous Chores
+
+* **api-service:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/api-models bumped from 0.0.3-next.5 to 0.0.3-next.6
+
+## [0.0.3-next.5](https://github.com/twinfoundation/api/compare/api-service-v0.0.3-next.4...api-service-v0.0.3-next.5) (2025-11-14)
+
+
+### Miscellaneous Chores
+
+* **api-service:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/api-models bumped from 0.0.3-next.4 to 0.0.3-next.5
+
+## [0.0.3-next.4](https://github.com/twinfoundation/api/compare/api-service-v0.0.3-next.3...api-service-v0.0.3-next.4) (2025-11-14)
+
+
+### Features
+
+* add context id features ([#42](https://github.com/twinfoundation/api/issues/42)) ([0186055](https://github.com/twinfoundation/api/commit/0186055c48afde842a4254b4df9ac9249c40fe40))
+* add root, favicon routes ([71da1c3](https://github.com/twinfoundation/api/commit/71da1c3a93c349588aff7084d1d8d6a29a277da8))
+* add validate-locales ([cdba610](https://github.com/twinfoundation/api/commit/cdba610a0acb5022d2e3ce729732e6646a297e5e))
+* eslint migration to flat config ([0dd5820](https://github.com/twinfoundation/api/commit/0dd5820e3af97350fd08b8d226f4a6c1a9246805))
+* remove unused namespace ([08478f2](https://github.com/twinfoundation/api/commit/08478f27efda9beb0271fdb22f6972e918361965))
+* update dependencies ([1171dc4](https://github.com/twinfoundation/api/commit/1171dc416a9481737f6a640e3cf30145768f37e9))
+* update framework core ([d8eebf2](https://github.com/twinfoundation/api/commit/d8eebf267fa2a0abaa84e58590496e9d20490cfa))
+* update IComponent signatures ([915ce37](https://github.com/twinfoundation/api/commit/915ce37712326ab4aa6869c350eabaa4622e8430))
+* use shared store mechanism ([#19](https://github.com/twinfoundation/api/issues/19)) ([32116df](https://github.com/twinfoundation/api/commit/32116df3b4380a30137f5056f242a5c99afa2df9))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/api-models bumped from 0.0.3-next.3 to 0.0.3-next.4
+
+## [0.0.3-next.3](https://github.com/twinfoundation/api/compare/api-service-v0.0.3-next.2...api-service-v0.0.3-next.3) (2025-11-14)
+
+
+### Miscellaneous Chores
+
+* **api-service:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/api-models bumped from 0.0.3-next.2 to 0.0.3-next.3
 
 ## [0.0.3-next.2](https://github.com/twinfoundation/api/compare/api-service-v0.0.3-next.1...api-service-v0.0.3-next.2) (2025-11-12)
 

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/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
+
+> `readonly` `static` **CLASS\_NAME**: `string`
+
+Runtime name for the class.
+
+## Methods
+
+### className()
+
+> **className**(): `string`
+
+Returns the class name of the component.
+
+#### Returns
+
+`string`
+
+The class name of the component.
+
+#### Implementation of
+
+`IHostingComponent.className`
+
+***
+
+### 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**(`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**(`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

@@ -144,6 +144,24 @@ The OpenAPI spec.
 
 ***
 
+### livez()
+
+> **livez**(): `Promise`\<`boolean`\>
+
+Is the server live.
+
+#### Returns
+
+`Promise`\<`boolean`\>
+
+True if the server is live.
+
+#### Implementation of
+
+`IInformationComponent.livez`
+
+***
+
 ### health()
 
 > **health**(): `Promise`\<`IHealthInfo`\>
@@ -164,7 +182,7 @@ The service health.
 
 ### setComponentHealth()
 
-> **setComponentHealth**(`name`, `status`, `details?`): `Promise`\<`void`\>
+> **setComponentHealth**(`name`, `status`, `details?`, `tenantId?`): `Promise`\<`void`\>
 
 Set the status of a component.
 
@@ -188,6 +206,12 @@ The status of the component.
 
 The details for the status.
 
+##### tenantId?
+
+`string`
+
+The tenant id, optional if the health status is not tenant specific.
+
 #### Returns
 
 `Promise`\<`void`\>
@@ -202,7 +226,7 @@ Nothing.
 
 ### removeComponentHealth()
 
-> **removeComponentHealth**(`name`): `Promise`\<`void`\>
+> **removeComponentHealth**(`name`, `tenantId?`): `Promise`\<`void`\>
 
 Remove the status of a component.
 
@@ -214,6 +238,12 @@ Remove the status of a component.
 
 The component name.
 
+##### tenantId?
+
+`string`
+
+The tenant id, optional if the health status is not tenant specific.
+
 #### Returns
 
 `Promise`\<`void`\>

package/docs/reference/functions/serverLivez.md

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

package/docs/reference/index.md

@@ -2,10 +2,13 @@
 
 ## Classes
 
+- [HostingService](classes/HostingService.md)
 - [InformationService](classes/InformationService.md)
 
 ## Interfaces
 
+- [IHostingServiceConfig](interfaces/IHostingServiceConfig.md)
+- [IHostingServiceConstructorOptions](interfaces/IHostingServiceConstructorOptions.md)
 - [IInformationServiceConfig](interfaces/IInformationServiceConfig.md)
 - [IInformationServiceConstructorOptions](interfaces/IInformationServiceConstructorOptions.md)
 
@@ -19,6 +22,7 @@
 - [generateRestRoutesInformation](functions/generateRestRoutesInformation.md)
 - [serverRoot](functions/serverRoot.md)
 - [serverInfo](functions/serverInfo.md)
+- [serverLivez](functions/serverLivez.md)
 - [serverHealth](functions/serverHealth.md)
 - [serverFavIcon](functions/serverFavIcon.md)
 - [serverSpec](functions/serverSpec.md)

package/docs/reference/interfaces/IHostingServiceConfig.md

@@ -0,0 +1,19 @@
+# Interface: IHostingServiceConfig
+
+Configuration for the hosting service.
+
+## Properties
+
+### localOrigin
+
+> **localOrigin**: `string`
+
+The local origin, must be provided as a fallback e.g. http://localhost:1234.
+
+***
+
+### publicOrigin?
+
+> `optional` **publicOrigin**: `string`
+
+The APIs public base URL e.g. "https://api.example.com:1234".

package/docs/reference/interfaces/IHostingServiceConstructorOptions.md

@@ -0,0 +1,19 @@
+# Interface: IHostingServiceConstructorOptions
+
+Options for the IHostingService constructor.
+
+## Properties
+
+### tenantAdminComponentType?
+
+> `optional` **tenantAdminComponentType**: `string`
+
+The tenant admin component type.
+
+***
+
+### config
+
+> **config**: [`IHostingServiceConfig`](IHostingServiceConfig.md)
+
+The configuration for the service.

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@twin.org/api-service",
-	"version": "0.0.3-next.2",
-	"description": "Information contract implementation and REST endpoint definitions",
+	"version": "0.0.3-next.21",
+	"description": "Information and hosting service implementations with generated REST route handlers.",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/twinfoundation/api.git",
@@ -14,7 +14,8 @@
 		"node": ">=20.0.0"
 	},
 	"dependencies": {
-		"@twin.org/api-models": "0.0.3-next.2",
+		"@twin.org/api-models": "0.0.3-next.21",
+		"@twin.org/context": "next",
 		"@twin.org/core": "next",
 		"@twin.org/nameof": "next",
 		"@twin.org/web": "next"