@twin.org/api-models 0.0.3-next.3 → 0.0.3-next.31

package/docs/examples.md

@@ -1 +1,200 @@
-# @twin.org/api-models - Examples
+# Models Examples
+
+These snippets show practical helpers for URL manipulation, request parameter conversion, consistent error responses, and secure parameter encryption.
+
+## 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
+}
+```
+
+## IHostingComponent
+
+When working with the hosting component, you can encrypt and decrypt query parameters for secure transmission. The encryption mechanism automatically handles salt generation to prevent rainbow table attacks.
+
+```typescript
+import type { IComponent, IHttpRequestQuery } from '@twin.org/api-models';
+import { ComponentFactory } from '@twin.org/core';
+
+interface IHostingComponent extends IComponent {
+  addEncryptedParamsToUrl(url: string, params: IHttpRequestQuery): Promise<string>;
+  getDecryptedParamsFromQueryParams(
+    queryParams: IHttpRequestQuery | undefined,
+    keys: string[]
+  ): Promise<IHttpRequestQuery>;
+  encryptParam(paramValue: string): Promise<string>;
+  decryptParam(encryptedValue: string): Promise<string>;
+}
+
+// Get the hosting component from the component factory
+const hosting = ComponentFactory.get<IHostingComponent>('hosting');
+
+// Encrypt parameters and add them to a URL
+const baseUrl = 'https://api.example.com/callback';
+const encrypted = await hosting.addEncryptedParamsToUrl(baseUrl, {
+  token: 'secret-token-123',
+  userId: 'user-456'
+});
+console.log(encrypted); // https://api.example.com/callback?x-enc-token=...&x-enc-userId=...
+```
+
+```typescript
+import type { IHttpRequestQuery } from '@twin.org/api-models';
+import { ComponentFactory } from '@twin.org/core';
+
+interface IHostingComponent {
+  addEncryptedParamsToUrl(url: string, params: IHttpRequestQuery): Promise<string>;
+  getDecryptedParamsFromQueryParams(
+    queryParams: IHttpRequestQuery | undefined,
+    keys: string[]
+  ): Promise<IHttpRequestQuery>;
+  encryptQueryParams(
+    httpRequestQuery: IHttpRequestQuery | undefined,
+    keys: string[]
+  ): Promise<void>;
+  decryptQueryParams(
+    httpRequestQuery: IHttpRequestQuery | undefined,
+    keys: string[]
+  ): Promise<void>;
+}
+
+const hosting = ComponentFactory.get<IHostingComponent>('hosting');
+
+// Decrypt specific parameters from a query object
+const queryParams: IHttpRequestQuery = {
+  'x-enc-token': 'CngBAgMEBQYH...',
+  'x-enc-userId': 'CxgICSoLDAwN...',
+  status: 'active'
+};
+
+const decrypted = await hosting.getDecryptedParamsFromQueryParams(queryParams, ['token', 'userId']);
+console.log(decrypted); // { token: 'secret-token-123', userId: 'user-456' }
+```
+
+```typescript
+import type { IHttpRequestQuery } from '@twin.org/api-models';
+import { ComponentFactory } from '@twin.org/core';
+
+interface IHostingComponent {
+  addTenantTokenToUrl(url: string, tenantId: string): Promise<string>;
+  getTenantTokenFromQueryParams(
+    queryParams: IHttpRequestQuery | undefined
+  ): Promise<string | undefined>;
+}
+
+const hosting = ComponentFactory.get<IHostingComponent>('hosting');
+
+// Add encrypted tenant token to a URL
+const redirectUrl = 'https://tenant.example.com/dashboard';
+const urlWithTenant = await hosting.addTenantTokenToUrl(
+  redirectUrl,
+  'a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6'
+);
+console.log(urlWithTenant); // https://tenant.example.com/dashboard?x-enc-tenant-token=...
+```
+
+```typescript
+import type { IHttpRequestQuery } from '@twin.org/api-models';
+import { ComponentFactory } from '@twin.org/core';
+
+interface IHostingComponent {
+  encryptQueryParams(
+    httpRequestQuery: IHttpRequestQuery | undefined,
+    keys: string[]
+  ): Promise<void>;
+  decryptQueryParams(
+    httpRequestQuery: IHttpRequestQuery | undefined,
+    keys: string[]
+  ): Promise<void>;
+}
+
+const hosting = ComponentFactory.get<IHostingComponent>('hosting');
+
+// Encrypt specific query parameters in place
+const query: IHttpRequestQuery = {
+  token: 'secret-123',
+  apiKey: 'key-456',
+  status: 'active'
+};
+
+await hosting.encryptQueryParams(query, ['token', 'apiKey']);
+console.log(query); // { 'x-enc-token': '...', 'x-enc-apiKey': '...', status: 'active' }
+
+// Decrypt the parameters back to their original keys
+await hosting.decryptQueryParams(query, ['token', 'apiKey']);
+console.log(query); // { token: 'secret-123', apiKey: 'key-456', status: 'active' }
+```
+
+```typescript
+import { ComponentFactory } from '@twin.org/core';
+
+interface IHostingComponent {
+  encryptParam(paramValue: string): Promise<string>;
+  decryptParam(encryptedValue: string): Promise<string>;
+}
+
+const hosting = ComponentFactory.get<IHostingComponent>('hosting');
+
+// Encrypt a single parameter value
+const plainText = 'confidential-data';
+const encrypted = await hosting.encryptParam(plainText);
+console.log(encrypted); // CngBAgMEBQYHCAkKCwwNDg8QERAh...
+
+// Decrypt the parameter value
+const decrypted = await hosting.decryptParam(encrypted);
+console.log(decrypted); // confidential-data
+```

package/docs/reference/classes/ForbiddenError.md

@@ -0,0 +1,55 @@
+# Class: ForbiddenError
+
+Class to handle errors which are triggered by forbidden actions.
+
+## Extends
+
+- `BaseError`
+
+## Constructors
+
+### Constructor
+
+> **new ForbiddenError**(`source`, `message`, `properties?`, `cause?`): `ForbiddenError`
+
+Create a new instance of ForbiddenError.
+
+#### Parameters
+
+##### source
+
+`string`
+
+The source of the error.
+
+##### message
+
+`string`
+
+The message as a code.
+
+##### properties?
+
+Any additional information for the error.
+
+##### cause?
+
+`unknown`
+
+The cause of the error if we have wrapped another error.
+
+#### Returns
+
+`ForbiddenError`
+
+#### Overrides
+
+`BaseError.constructor`
+
+## Properties
+
+### CLASS\_NAME {#class_name}
+
+> `readonly` `static` **CLASS\_NAME**: `string`
+
+Runtime name for the class.

package/docs/reference/classes/HttpErrorHelper.md

@@ -12,9 +12,21 @@ Class to help with processing http errors.
 
 `HttpErrorHelper`
 
+## Properties
+
+### ERROR\_TYPE\_MAP {#error_type_map}
+
+> `readonly` `static` **ERROR\_TYPE\_MAP**: `object`
+
+Mapping of error types to status codes.
+
+#### Index Signature
+
+\[`id`: `string`\]: `HttpStatusCode`
+
 ## Methods
 
-### processError()
+### processError() {#processerror}
 
 > `static` **processError**(`err`, `includeStack?`): `object`
 
@@ -50,7 +62,7 @@ The status code and additional error data.
 
 ***
 
-### buildResponse()
+### buildResponse() {#buildresponse}
 
 > `static` **buildResponse**(`response`, `error`, `statusCode`): `void`
 

package/docs/reference/classes/HttpParameterHelper.md

@@ -14,7 +14,7 @@ Class to help with handling http parameters.
 
 ## Methods
 
-### arrayFromString()
+### arrayFromString() {#arrayfromstring}
 
 > `static` **arrayFromString**\<`T`\>(`values?`): `T`[] \| `undefined`
 
@@ -42,7 +42,7 @@ The array of values.
 
 ***
 
-### arrayToString()
+### arrayToString() {#arraytostring}
 
 > `static` **arrayToString**\<`T`\>(`values?`): `string` \| `undefined`
 
@@ -70,7 +70,7 @@ The combined.
 
 ***
 
-### objectFromString()
+### objectFromString() {#objectfromstring}
 
 > `static` **objectFromString**\<`T`\>(`value?`): `T` \| `undefined`
 
@@ -98,7 +98,7 @@ The object.
 
 ***
 
-### objectToString()
+### objectToString() {#objecttostring}
 
 > `static` **objectToString**\<`T`\>(`value?`): `string` \| `undefined`
 

package/docs/reference/classes/HttpUrlHelper.md

@@ -0,0 +1,197 @@
+# Class: HttpUrlHelper
+
+Class to help with handling http URLs.
+
+## Constructors
+
+### Constructor
+
+> **new HttpUrlHelper**(): `HttpUrlHelper`
+
+#### Returns
+
+`HttpUrlHelper`
+
+## Methods
+
+### extractOrigin() {#extractorigin}
+
+> `static` **extractOrigin**(`url`): `string` \| `undefined`
+
+Extract the origin from the url which includes protocol,host,port.
+
+#### Parameters
+
+##### url
+
+`string`
+
+The url to extract the origin from.
+
+#### Returns
+
+`string` \| `undefined`
+
+The extracted origin.
+
+#### See
+
+https://developer.mozilla.org/en-US/docs/Web/API/URL/origin
+
+***
+
+### extractPath() {#extractpath}
+
+> `static` **extractPath**(`url`): `string` \| `undefined`
+
+Extract the path from the url.
+
+#### Parameters
+
+##### url
+
+`string`
+
+The url to extract the path from.
+
+#### Returns
+
+`string` \| `undefined`
+
+The extracted path.
+
+#### See
+
+https://developer.mozilla.org/en-US/docs/Web/API/URL/pathname
+
+***
+
+### extractSearch() {#extractsearch}
+
+> `static` **extractSearch**(`url`): `string` \| `undefined`
+
+Extract the search from the url.
+
+#### Parameters
+
+##### url
+
+`string`
+
+The url to extract the search from.
+
+#### Returns
+
+`string` \| `undefined`
+
+The extracted search.
+
+#### See
+
+https://developer.mozilla.org/en-US/docs/Web/API/URL/search
+
+***
+
+### extractPathAndSearch() {#extractpathandsearch}
+
+> `static` **extractPathAndSearch**(`url`): `string` \| `undefined`
+
+Extract the path and search from the url.
+
+#### Parameters
+
+##### url
+
+`string`
+
+The url to extract the path and search from.
+
+#### Returns
+
+`string` \| `undefined`
+
+The extracted path and search.
+
+***
+
+### combineParts() {#combineparts}
+
+> `static` **combineParts**(`origin`, `pathAndSearch`): `string` \| `undefined`
+
+Combine the urls parts.
+
+#### Parameters
+
+##### origin
+
+`string`
+
+The origin to combine.
+
+##### pathAndSearch
+
+`string`
+
+The path and search to combine.
+
+#### Returns
+
+`string` \| `undefined`
+
+The combined parts.
+
+***
+
+### encodeUriPathSegment() {#encodeuripathsegment}
+
+> `static` **encodeUriPathSegment**(`segment`): `string`
+
+Encode a single URL path segment per RFC 3986 §3.3.
+Unlike encodeURIComponent, sub-delimiters ($ & + , ; =) and the colon and
+at-sign characters that are valid unencoded in path segments are preserved.
+
+#### Parameters
+
+##### segment
+
+`string`
+
+The raw path segment value to encode.
+
+#### Returns
+
+`string`
+
+The percent-encoded path segment.
+
+#### See
+
+https://datatracker.ietf.org/doc/html/rfc3986#section-3.3
+
+***
+
+### replaceOrigin() {#replaceorigin}
+
+> `static` **replaceOrigin**(`url`, `newOrigin?`): `string`
+
+Replace the origin in the url.
+
+#### Parameters
+
+##### url
+
+`string`
+
+The url to replace the origin in.
+
+##### newOrigin?
+
+`string`
+
+The new origin to use.
+
+#### Returns
+
+`string`
+
+The url with the replaced origin.

package/docs/reference/classes/TooManyRequestsError.md

@@ -0,0 +1,67 @@
+# Class: TooManyRequestsError
+
+Class to handle errors which are triggered by too many requests.
+
+## Extends
+
+- `BaseError`
+
+## Constructors
+
+### Constructor
+
+> **new TooManyRequestsError**(`source`, `message`, `requestCount`, `nextRequestTime`, `properties?`, `cause?`): `TooManyRequestsError`
+
+Create a new instance of TooManyRequestsError.
+
+#### Parameters
+
+##### source
+
+`string`
+
+The source of the error.
+
+##### message
+
+`string`
+
+The message as a code.
+
+##### requestCount
+
+`number`
+
+The current request count.
+
+##### nextRequestTime
+
+`string`
+
+The time when the next request can be made, as date ISO string.
+
+##### properties?
+
+Any additional information for the error.
+
+##### cause?
+
+`unknown`
+
+The cause of the error if we have wrapped another error.
+
+#### Returns
+
+`TooManyRequestsError`
+
+#### Overrides
+
+`BaseError.constructor`
+
+## Properties
+
+### CLASS\_NAME {#class_name}
+
+> `readonly` `static` **CLASS\_NAME**: `string`
+
+Runtime name for the class.

package/docs/reference/index.md

@@ -2,17 +2,21 @@
 
 ## Classes
 
+- [ForbiddenError](classes/ForbiddenError.md)
+- [TooManyRequestsError](classes/TooManyRequestsError.md)
 - [HttpErrorHelper](classes/HttpErrorHelper.md)
 - [HttpParameterHelper](classes/HttpParameterHelper.md)
+- [HttpUrlHelper](classes/HttpUrlHelper.md)
 
 ## Interfaces
 
 - [IServerFavIconResponse](interfaces/IServerFavIconResponse.md)
 - [IServerHealthResponse](interfaces/IServerHealthResponse.md)
 - [IServerInfoResponse](interfaces/IServerInfoResponse.md)
+- [IServerLivezResponse](interfaces/IServerLivezResponse.md)
+- [IServerReadyzResponse](interfaces/IServerReadyzResponse.md)
 - [IServerRootResponse](interfaces/IServerRootResponse.md)
 - [IServerSpecResponse](interfaces/IServerSpecResponse.md)
-- [IAuthenticationGenerator](interfaces/IAuthenticationGenerator.md)
 - [IBaseRestClientConfig](interfaces/IBaseRestClientConfig.md)
 - [IBaseSocketClientConfig](interfaces/IBaseSocketClientConfig.md)
 - [IHttpRequest](interfaces/IHttpRequest.md)
@@ -29,6 +33,8 @@
 - [IForbiddenResponse](interfaces/IForbiddenResponse.md)
 - [IInternalServerErrorResponse](interfaces/IInternalServerErrorResponse.md)
 - [INotFoundResponse](interfaces/INotFoundResponse.md)
+- [INotImplementedResponse](interfaces/INotImplementedResponse.md)
+- [ITooManyRequestsResponse](interfaces/ITooManyRequestsResponse.md)
 - [IUnauthorizedResponse](interfaces/IUnauthorizedResponse.md)
 - [IUnprocessableEntityResponse](interfaces/IUnprocessableEntityResponse.md)
 - [IAcceptedResponse](interfaces/IAcceptedResponse.md)
@@ -51,20 +57,23 @@
 - [ISocketRouteProcessor](interfaces/ISocketRouteProcessor.md)
 - [IWebServer](interfaces/IWebServer.md)
 - [IWebServerOptions](interfaces/IWebServerOptions.md)
-- [IHealthInfo](interfaces/IHealthInfo.md)
+- [IHealthComponent](interfaces/IHealthComponent.md)
+- [IHostingComponent](interfaces/IHostingComponent.md)
 - [IInformationComponent](interfaces/IInformationComponent.md)
 - [IServerInfo](interfaces/IServerInfo.md)
+- [ITenant](interfaces/ITenant.md)
+- [ITenantAdminComponent](interfaces/ITenantAdminComponent.md)
+- [IUrlTransformerComponent](interfaces/IUrlTransformerComponent.md)
 
 ## Type Aliases
 
+- [HttpContextIdKeys](type-aliases/HttpContextIdKeys.md)
 - [IRestRouteEntryPoint](type-aliases/IRestRouteEntryPoint.md)
 - [ISocketRouteEntryPoint](type-aliases/ISocketRouteEntryPoint.md)
-- [HealthStatus](type-aliases/HealthStatus.md)
 
 ## Variables
 
-- [AuthenticationGeneratorFactory](variables/AuthenticationGeneratorFactory.md)
 - [MimeTypeProcessorFactory](variables/MimeTypeProcessorFactory.md)
 - [RestRouteProcessorFactory](variables/RestRouteProcessorFactory.md)
 - [SocketRouteProcessorFactory](variables/SocketRouteProcessorFactory.md)
-- [HealthStatus](variables/HealthStatus.md)
+- [HttpContextIdKeys](variables/HttpContextIdKeys.md)

package/docs/reference/interfaces/IAcceptedResponse.md

@@ -4,7 +4,7 @@ The rest request ended in accepted response.
 
 ## Properties
 
-### statusCode
+### statusCode {#statuscode}
 
 > **statusCode**: `202`
 
@@ -12,7 +12,7 @@ Response status code.
 
 ***
 
-### headers
+### headers {#headers}
 
 > **headers**: `object`
 

package/docs/reference/interfaces/IBadRequestResponse.md

@@ -4,7 +4,7 @@ The server cannot process the request, see the content for more details.
 
 ## Properties
 
-### statusCode
+### statusCode {#statuscode}
 
 > **statusCode**: `400`
 
@@ -12,7 +12,7 @@ Response status code.
 
 ***
 
-### body
+### body {#body}
 
 > **body**: `IError`