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

package/dist/types/models/protocol/IHttpServerRequest.d.ts

@@ -5,11 +5,11 @@ import type { IHttpRequest } from "./IHttpRequest.js";
  */
 export interface IHttpServerRequest<T = any> extends IHttpRequest<T> {
     /**
-     * The request method.
+     * The request url.
      */
-    method?: HttpMethod;
+    url: string;
     /**
-     * The request url.
+     * The request method.
      */
-    url?: string;
+    method?: HttpMethod;
 }

package/dist/types/models/routes/IBaseRoute.d.ts

@@ -11,9 +11,17 @@ export interface IBaseRoute {
      */
     path: string;
     /**
-     * Skips the authentication for this route.
+     * Skips the authentication requirement for this route.
      */
     skipAuth?: boolean;
+    /**
+     * Skips the tenant requirement for this route.
+     */
+    skipTenant?: boolean;
+    /**
+     * The user must have one of the specified scopes to access the route.
+     */
+    requiredScope?: string[];
     /**
      * The features supported by additional processors to run for this route.
      */

package/dist/types/models/server/IBaseRouteProcessor.d.ts

@@ -21,12 +21,17 @@ export interface IBaseRouteProcessor<T = IBaseRoute, R = IHttpServerRequest> ext
      * @param route The route being requested, if a matching one was found.
      * @param contextIds The context IDs of the request.
      * @param processorState The state handed through the processors.
-     * @param loggingComponentType The logging component type for the request.
+     * @param componentTypes The component types for the request.
+     * @param componentTypes.loggingComponentType The logging component type.
+     * @param componentTypes.hostingComponentType The hosting component type.
      * @returns Promise that resolves when the request is processed.
      */
     pre?(request: R, response: IHttpResponse, route: T | undefined, contextIds: IContextIds, processorState: {
         [id: string]: unknown;
-    }, loggingComponentType?: string): Promise<void>;
+    }, componentTypes?: {
+        loggingComponentType?: string;
+        hostingComponentType?: string;
+    }): Promise<void>;
     /**
      * Post process the REST request for the specified route.
      * @param request The request to handle.
@@ -34,10 +39,15 @@ export interface IBaseRouteProcessor<T = IBaseRoute, R = IHttpServerRequest> ext
      * @param route The route being requested, if a matching one was found.
      * @param contextIds The context IDs of the request.
      * @param processorState The state handed through the processors.
-     * @param loggingComponentType The logging component type for the request.
+     * @param componentTypes The component types for the request.
+     * @param componentTypes.loggingComponentType The logging component type.
+     * @param componentTypes.hostingComponentType The hosting component type.
      * @returns Promise that resolves when the request is processed.
      */
     post?(request: R, response: IHttpResponse, route: T | undefined, contextIds: IContextIds, processorState: {
         [id: string]: unknown;
-    }, loggingComponentType?: string): Promise<void>;
+    }, componentTypes?: {
+        loggingComponentType?: string;
+        hostingComponentType?: string;
+    }): Promise<void>;
 }

package/dist/types/models/server/IRestRouteProcessor.d.ts

@@ -12,10 +12,15 @@ export interface IRestRouteProcessor extends IBaseRouteProcessor<IRestRoute> {
      * @param response The response data to send if any.
      * @param route The route being requested, if a matching one was found.
      * @param processorState The state handed through the processors.
-     * @param loggingComponentType The logging component type for the request.
+     * @param componentTypes The component types for the request.
+     * @param componentTypes.loggingComponentType The logging component type.
+     * @param componentTypes.hostingComponentType The hosting component type.
      * @returns Promise that resolves when the request is processed.
      */
     process?(request: IHttpServerRequest, response: IHttpResponse, route: IRestRoute | undefined, processorState: {
         [id: string]: unknown;
-    }, loggingComponentType?: string): Promise<void>;
+    }, componentTypes?: {
+        loggingComponentType?: string;
+        hostingComponentType?: string;
+    }): Promise<void>;
 }

package/dist/types/models/services/IHealthComponentInfo.d.ts

@@ -0,0 +1,18 @@
+import type { HealthStatus } from "./healthStatus.js";
+/**
+ * The health component information.
+ */
+export interface IHealthComponentInfo {
+    /**
+     * The name of the component.
+     */
+    name: string;
+    /**
+     * The status of the component.
+     */
+    status: HealthStatus;
+    /**
+     * The details for the status.
+     */
+    details?: string;
+}

package/dist/types/models/services/IHealthInfo.d.ts

@@ -1,4 +1,5 @@
 import type { HealthStatus } from "./healthStatus.js";
+import type { IHealthComponentInfo } from "./IHealthComponentInfo.js";
 /**
  * The status of the server.
  */
@@ -10,18 +11,5 @@ export interface IHealthInfo {
     /**
      * The status of the components.
      */
-    components?: {
-        /**
-         * The name of the component.
-         */
-        name: string;
-        /**
-         * The status of the component.
-         */
-        status: HealthStatus;
-        /**
-         * The details for the status.
-         */
-        details?: string;
-    }[];
+    components?: IHealthComponentInfo[];
 }

package/dist/types/models/services/IHostingComponent.d.ts

@@ -0,0 +1,24 @@
+import type { IComponent } from "@twin.org/core";
+/**
+ * The information about the hosting of the API.
+ */
+export interface IHostingComponent extends IComponent {
+    /**
+     * Get the public origin for the hosting.
+     * @param serverRequestUrl The url of the current server request if there is one.
+     * @returns The public origin.
+     */
+    getPublicOrigin(serverRequestUrl?: string): Promise<string>;
+    /**
+     * Get the public origin for the tenant if one exists.
+     * @param tenantId The tenant identifier.
+     * @returns The public origin for the tenant.
+     */
+    getTenantOrigin(tenantId: string): Promise<string | undefined>;
+    /**
+     * Build a public url based on the public origin and the url provided.
+     * @param url The url to build upon the public origin.
+     * @returns The full url based on the public origin.
+     */
+    buildPublicUrl(url: string): Promise<string>;
+}

package/dist/types/models/services/IInformationComponent.d.ts

@@ -26,6 +26,11 @@ export interface IInformationComponent extends IComponent {
      * @returns The OpenAPI spec.
      */
     spec(): Promise<unknown>;
+    /**
+     * Is the server live.
+     * @returns True if the server is live.
+     */
+    livez(): Promise<boolean>;
     /**
      * Get the server health.
      * @returns The service health.
@@ -36,13 +41,15 @@ export interface IInformationComponent extends IComponent {
      * @param name The component name.
      * @param status The status of the component.
      * @param details The details for the status.
+     * @param tenantId The tenant id, optional if the health status is not tenant specific.
      * @returns Nothing.
      */
-    setComponentHealth(name: string, status: HealthStatus, details?: string): Promise<void>;
+    setComponentHealth(name: string, status: HealthStatus, details?: string, tenantId?: string): Promise<void>;
     /**
      * Remove the status of a component.
      * @param name The component name.
+     * @param tenantId The tenant id, optional if the health status is not tenant specific.
      * @returns Nothing.
      */
-    removeComponentHealth(name: string): Promise<void>;
+    removeComponentHealth(name: string, tenantId?: string): Promise<void>;
 }

package/dist/types/models/services/ITenant.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Model defining the tenant.
+ */
+export interface ITenant {
+    /**
+     * The unique identifier for the tenant.
+     */
+    id: string;
+    /**
+     * The api key for the tenant.
+     */
+    apiKey: string;
+    /**
+     * The label of the tenant.
+     */
+    label: string;
+    /**
+     * The date the tenant was created.
+     */
+    dateCreated: string;
+    /**
+     * The date the tenant was modified.
+     */
+    dateModified: string;
+    /**
+     * The public origin available to the public for accessing the API.
+     */
+    publicOrigin?: string;
+    /**
+     * Indicates whether the tenant is the node tenant.
+     */
+    isNodeTenant: boolean;
+}

package/dist/types/models/services/ITenantAdminComponent.d.ts

@@ -0,0 +1,63 @@
+import type { IComponent } from "@twin.org/core";
+import type { ITenant } from "./ITenant.js";
+/**
+ * Configuration for the tenant admin component
+ */
+export interface ITenantAdminComponent extends IComponent {
+    /**
+     * Create a tenant.
+     * @param tenant The tenant to store.
+     * @returns The tenant id.
+     */
+    create(tenant: Omit<ITenant, "id" | "dateCreated" | "dateModified"> & {
+        id?: string;
+    }): Promise<string>;
+    /**
+     * Update a tenant.
+     * @param tenant The tenant to update.
+     * @returns Nothing.
+     */
+    update(tenant: Partial<Omit<ITenant, "dateCreated" | "dateModified">>): Promise<void>;
+    /**
+     * Get a tenant by its id.
+     * @param tenantId The id of the tenant.
+     * @returns The tenant.
+     * @throws Error if the tenant is not found.
+     */
+    get(tenantId: string): Promise<ITenant>;
+    /**
+     * Get a tenant by its api key.
+     * @param apiKey The api key of the tenant.
+     * @returns The tenant.
+     * @throws Error if the tenant is not found.
+     */
+    getByApiKey(apiKey: string): Promise<ITenant>;
+    /**
+     * Get a tenant by its public origin.
+     * @param publicOrigin The origin of the tenant.
+     * @returns The tenant.
+     * @throws Error if the tenant is not found.
+     */
+    getByPublicOrigin(publicOrigin: string): Promise<ITenant>;
+    /**
+     * Remove a tenant by its id.
+     * @param tenantId The id of the tenant.
+     * @returns Nothing.
+     * @throws Error if the tenant is not found.
+     */
+    remove(tenantId: string): Promise<void>;
+    /**
+     * Query tenants with pagination.
+     * @param options Optional query options.
+     * @param options.isNodeTenant Whether to filter for node admin tenants.
+     * @param cursor The cursor to start from.
+     * @param limit The maximum number of tenants to return.
+     * @returns The tenants and the next cursor if more tenants are available.
+     */
+    query(options?: {
+        isNodeTenant?: boolean;
+    }, cursor?: string, limit?: number): Promise<{
+        tenants: ITenant[];
+        cursor?: string;
+    }>;
+}

package/docs/changelog.md

@@ -1,4 +1,168 @@
-# @twin.org/api-models - Changelog
+# Changelog
+
+## [0.0.3-next.21](https://github.com/twinfoundation/api/compare/api-models-v0.0.3-next.20...api-models-v0.0.3-next.21) (2026-03-11)
+
+
+### Miscellaneous Chores
+
+* **api-models:** Synchronize repo versions
+
+## [0.0.3-next.20](https://github.com/twinfoundation/api/compare/api-models-v0.0.3-next.19...api-models-v0.0.3-next.20) (2026-02-09)
+
+
+### Miscellaneous Chores
+
+* **api-models:** Synchronize repo versions
+
+## [0.0.3-next.19](https://github.com/twinfoundation/api/compare/api-models-v0.0.3-next.18...api-models-v0.0.3-next.19) (2026-02-06)
+
+
+### Miscellaneous Chores
+
+* **api-models:** Synchronize repo versions
+
+## [0.0.3-next.18](https://github.com/twinfoundation/api/compare/api-models-v0.0.3-next.17...api-models-v0.0.3-next.18) (2026-02-04)
+
+
+### Features
+
+* tenant api and scopes ([#75](https://github.com/twinfoundation/api/issues/75)) ([c663141](https://github.com/twinfoundation/api/commit/c663141091e8974d769f8f9904ecdab009ebd083))
+
+## [0.0.3-next.17](https://github.com/twinfoundation/api/compare/api-models-v0.0.3-next.16...api-models-v0.0.3-next.17) (2026-01-26)
+
+
+### Features
+
+* update public origin building ([6c8e042](https://github.com/twinfoundation/api/commit/6c8e0422d9ddbed42a843e1c23498c99977b2fc7))
+
+## [0.0.3-next.16](https://github.com/twinfoundation/api/compare/api-models-v0.0.3-next.15...api-models-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))
+
+## [0.0.3-next.15](https://github.com/twinfoundation/api/compare/api-models-v0.0.3-next.14...api-models-v0.0.3-next.15) (2026-01-22)
+
+
+### Miscellaneous Chores
+
+* **api-models:** Synchronize repo versions
+
+## [0.0.3-next.14](https://github.com/twinfoundation/api/compare/api-models-v0.0.3-next.13...api-models-v0.0.3-next.14) (2026-01-20)
+
+
+### Features
+
+* export error type map ([#68](https://github.com/twinfoundation/api/issues/68)) ([697dfc4](https://github.com/twinfoundation/api/commit/697dfc4c9f6a7be493bf4b3619d7bcebf2e4584e))
+
+## [0.0.3-next.13](https://github.com/twinfoundation/api/compare/api-models-v0.0.3-next.12...api-models-v0.0.3-next.13) (2026-01-19)
+
+
+### Features
+
+* remove authentication generators ([#66](https://github.com/twinfoundation/api/issues/66)) ([adaa169](https://github.com/twinfoundation/api/commit/adaa1698df1c5ccb0ad645a7a7c0d3ef82ef6ac1))
+
+## [0.0.3-next.12](https://github.com/twinfoundation/api/compare/api-models-v0.0.3-next.11...api-models-v0.0.3-next.12) (2026-01-12)
+
+
+### Miscellaneous Chores
+
+* **api-models:** Synchronize repo versions
+
+## [0.0.3-next.11](https://github.com/twinfoundation/api/compare/api-models-v0.0.3-next.10...api-models-v0.0.3-next.11) (2026-01-08)
+
+
+### Miscellaneous Chores
+
+* **api-models:** Synchronize repo versions
+
+## [0.0.3-next.10](https://github.com/twinfoundation/api/compare/api-models-v0.0.3-next.9...api-models-v0.0.3-next.10) (2026-01-05)
+
+
+### Miscellaneous Chores
+
+* **api-models:** Synchronize repo versions
+
+## [0.0.3-next.9](https://github.com/twinfoundation/api/compare/api-models-v0.0.3-next.8...api-models-v0.0.3-next.9) (2026-01-05)
+
+
+### Features
+
+* add authentication generators and process features option ([a67edf1](https://github.com/twinfoundation/api/commit/a67edf1df212bd8ab94a40cddf5338551155696f))
+* 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 logging component type to request contexts ([210de1b](https://github.com/twinfoundation/api/commit/210de1b9e1c91079b59a2b90ddd57569668d647d))
+* add root, favicon routes ([71da1c3](https://github.com/twinfoundation/api/commit/71da1c3a93c349588aff7084d1d8d6a29a277da8))
+* add socket id, connect and disconnect ([20b0d0e](https://github.com/twinfoundation/api/commit/20b0d0ec279cab46141fee09de2c4a7087cdce16))
+* add validate-locales ([cdba610](https://github.com/twinfoundation/api/commit/cdba610a0acb5022d2e3ce729732e6646a297e5e))
+* decodeURIComponent for query and path params ([ead68a2](https://github.com/twinfoundation/api/commit/ead68a257425c10dd912497f7edd473c469ca132))
+* eslint migration to flat config ([0dd5820](https://github.com/twinfoundation/api/commit/0dd5820e3af97350fd08b8d226f4a6c1a9246805))
+* 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 new includeStackTrace flag for toJsonObject ([6452b15](https://github.com/twinfoundation/api/commit/6452b153af786eee14b21152420f8a2578b70593))
+* use shared store mechanism ([#19](https://github.com/twinfoundation/api/issues/19)) ([32116df](https://github.com/twinfoundation/api/commit/32116df3b4380a30137f5056f242a5c99afa2df9))
+* validationError mapped to http status badrequest ([adc5eb1](https://github.com/twinfoundation/api/commit/adc5eb11d987abb0ab9f7e0dc8e1fdae207e436e))
+
+
+### Bug Fixes
+
+* error handling make sure primary error takes precedence ([84b61f2](https://github.com/twinfoundation/api/commit/84b61f27fe5e4919c0c9f9a1edc8ff46dc45c1f7))
+
+## [0.0.3-next.8](https://github.com/twinfoundation/api/compare/api-models-v0.0.3-next.7...api-models-v0.0.3-next.8) (2025-12-17)
+
+
+### Miscellaneous Chores
+
+* **api-models:** Synchronize repo versions
+
+## [0.0.3-next.7](https://github.com/twinfoundation/api/compare/api-models-v0.0.3-next.6...api-models-v0.0.3-next.7) (2025-11-26)
+
+
+### Bug Fixes
+
+* error handling make sure primary error takes precedence ([84b61f2](https://github.com/twinfoundation/api/commit/84b61f27fe5e4919c0c9f9a1edc8ff46dc45c1f7))
+
+## [0.0.3-next.6](https://github.com/twinfoundation/api/compare/api-models-v0.0.3-next.5...api-models-v0.0.3-next.6) (2025-11-20)
+
+
+### Miscellaneous Chores
+
+* **api-models:** Synchronize repo versions
+
+## [0.0.3-next.5](https://github.com/twinfoundation/api/compare/api-models-v0.0.3-next.4...api-models-v0.0.3-next.5) (2025-11-14)
+
+
+### Features
+
+* decodeURIComponent for query and path params ([ead68a2](https://github.com/twinfoundation/api/commit/ead68a257425c10dd912497f7edd473c469ca132))
+
+## [0.0.3-next.4](https://github.com/twinfoundation/api/compare/api-models-v0.0.3-next.3...api-models-v0.0.3-next.4) (2025-11-14)
+
+
+### Features
+
+* add authentication generators and process features option ([a67edf1](https://github.com/twinfoundation/api/commit/a67edf1df212bd8ab94a40cddf5338551155696f))
+* add context id features ([#42](https://github.com/twinfoundation/api/issues/42)) ([0186055](https://github.com/twinfoundation/api/commit/0186055c48afde842a4254b4df9ac9249c40fe40))
+* add logging component type to request contexts ([210de1b](https://github.com/twinfoundation/api/commit/210de1b9e1c91079b59a2b90ddd57569668d647d))
+* add root, favicon routes ([71da1c3](https://github.com/twinfoundation/api/commit/71da1c3a93c349588aff7084d1d8d6a29a277da8))
+* add socket id, connect and disconnect ([20b0d0e](https://github.com/twinfoundation/api/commit/20b0d0ec279cab46141fee09de2c4a7087cdce16))
+* add validate-locales ([cdba610](https://github.com/twinfoundation/api/commit/cdba610a0acb5022d2e3ce729732e6646a297e5e))
+* eslint migration to flat config ([0dd5820](https://github.com/twinfoundation/api/commit/0dd5820e3af97350fd08b8d226f4a6c1a9246805))
+* 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 new includeStackTrace flag for toJsonObject ([6452b15](https://github.com/twinfoundation/api/commit/6452b153af786eee14b21152420f8a2578b70593))
+* use shared store mechanism ([#19](https://github.com/twinfoundation/api/issues/19)) ([32116df](https://github.com/twinfoundation/api/commit/32116df3b4380a30137f5056f242a5c99afa2df9))
+* validationError mapped to http status badrequest ([adc5eb1](https://github.com/twinfoundation/api/commit/adc5eb11d987abb0ab9f7e0dc8e1fdae207e436e))
+
+## [0.0.3-next.3](https://github.com/twinfoundation/api/compare/api-models-v0.0.3-next.2...api-models-v0.0.3-next.3) (2025-11-14)
+
+
+### Miscellaneous Chores
+
+* **api-models:** Synchronize repo versions
 
 ## [0.0.3-next.2](https://github.com/twinfoundation/api/compare/api-models-v0.0.3-next.1...api-models-v0.0.3-next.2) (2025-11-12)
 

package/docs/examples.md

@@ -1 +1,63 @@
-# @twin.org/api-models - Examples
+# Models Examples
+
+These snippets show practical helpers for URL manipulation, request parameter conversion, and consistent error responses.
+
+## HttpUrlHelper
+
+```typescript
+import { HttpUrlHelper } from '@twin.org/api-models';
+
+const fullUrl = 'https://tenant.example.org/orders?page=2';
+
+console.log(HttpUrlHelper.extractOrigin(fullUrl)); // https://tenant.example.org
+console.log(HttpUrlHelper.extractPath(fullUrl)); // /orders
+console.log(HttpUrlHelper.extractSearch(fullUrl)); // ?page=2
+console.log(HttpUrlHelper.extractPathAndSearch(fullUrl)); // /orders?page=2
+```
+
+```typescript
+import { HttpUrlHelper } from '@twin.org/api-models';
+
+const combined = HttpUrlHelper.combineParts('https://tenant.example.org/', '/api/v1/orders');
+const replaced = HttpUrlHelper.replaceOrigin(combined ?? '', 'https://edge.example.org');
+
+console.log(combined); // https://tenant.example.org/api/v1/orders
+console.log(replaced); // https://edge.example.org/api/v1/orders
+```
+
+## HttpParameterHelper
+
+```typescript
+import { HttpParameterHelper } from '@twin.org/api-models';
+
+const ids = HttpParameterHelper.arrayFromString('id-1,id-2,id-3');
+const idsAsString = HttpParameterHelper.arrayToString(ids);
+
+const filterObject = HttpParameterHelper.objectFromString('{"status":"active"}');
+const filterString = HttpParameterHelper.objectToString(filterObject);
+
+console.log(ids.length); // 3
+console.log(idsAsString); // id-1,id-2,id-3
+console.log(filterString); // {"status":"active"}
+```
+
+## HttpErrorHelper
+
+```typescript
+import { HttpErrorHelper } from '@twin.org/api-models';
+
+try {
+  throw new Error('Invalid request');
+} catch (err) {
+  const mapped = HttpErrorHelper.processError(err, false);
+  const response: {
+    body?: unknown;
+    statusCode?: number;
+    headers?: { [id: string]: string };
+  } = {};
+  HttpErrorHelper.buildResponse(response, mapped.error, mapped.httpStatusCode);
+
+  console.log(response.statusCode); // 500
+  console.log(mapped.error.message); // Error: Invalid request
+}
+```

package/docs/reference/classes/HttpErrorHelper.md

@@ -12,6 +12,18 @@ Class to help with processing http errors.
 
 `HttpErrorHelper`
 
+## Properties
+
+### ERROR\_TYPE\_MAP
+
+> `readonly` `static` **ERROR\_TYPE\_MAP**: `object`
+
+Mapping of error types to status codes.
+
+#### Index Signature
+
+\[`id`: `string`\]: `HttpStatusCode`
+
 ## Methods
 
 ### processError()