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

package/README.md

@@ -1,6 +1,6 @@
 # TWIN API Models
 
-Contains models for use with APIs.
+This package provides shared API contracts, route types, and response models used across services and clients.
 
 ## Installation
 

package/dist/es/models/server/ISocketRouteProcessor.js.map

@@ -1 +1 @@
-{"version":3,"file":"ISocketRouteProcessor.js","sourceRoot":"","sources":["../../../../src/models/server/ISocketRouteProcessor.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IBaseRouteProcessor } from \"./IBaseRouteProcessor.js\";\nimport type { IHttpResponse } from \"../protocol/IHttpResponse.js\";\nimport type { ISocketServerRequest } from \"../protocol/ISocketServerRequest.js\";\nimport type { ISocketRoute } from \"../routes/ISocketRoute.js\";\n\n/**\n * The definition for a processor for handling socket routes.\n */\nexport interface ISocketRouteProcessor\n\textends IBaseRouteProcessor<ISocketRoute, ISocketServerRequest> {\n\t/**\n\t * Process the connected event.\n\t * @param request The server request object containing the socket id and other parameters.\n\t * @param route The route being requested, if a matching one was found.\n\t * @param loggingComponentType The logging component type for the request.\n\t * @returns Promise that resolves when the request is processed.\n\t */\n\tconnected?(\n\t\trequest: ISocketServerRequest,\n\t\troute: ISocketRoute | undefined,\n\t\tloggingComponentType?: string\n\t): Promise<void>;\n\n\t/**\n\t * Process the disconnected event.\n\t * @param request The server request object containing the socket id and other parameters.\n\t * @param route The route being requested, if a matching one was found.\n\t * @param loggingComponentType The logging component type for the request.\n\t * @returns Promise that resolves when the request is processed.\n\t */\n\tdisconnected?(\n\t\trequest: ISocketServerRequest,\n\t\troute: ISocketRoute | undefined,\n\t\tloggingComponentType?: string\n\t): Promise<void>;\n\n\t/**\n\t * Process the REST request for the specified route.\n\t * @param request The server request object containing the socket id and other parameters.\n\t * @param response The response data to send if any.\n\t * @param route The route being requested, if a matching one was found.\n\t * @param processorState The state handed through the processors.\n\t * @param responseEmitter The function to emit a response.\n\t * @param loggingComponentType The logging component type for the request.\n\t * @returns Promise that resolves when the request is processed.\n\t */\n\tprocess?(\n\t\trequest: ISocketServerRequest,\n\t\tresponse: IHttpResponse,\n\t\troute: ISocketRoute | undefined,\n\t\tprocessorState: { [id: string]: unknown },\n\t\tresponseEmitter: (topic: string, response: IHttpResponse) => Promise<void>,\n\t\tloggingComponentType?: string\n\t): Promise<void>;\n}\n"]}
+{"version":3,"file":"ISocketRouteProcessor.js","sourceRoot":"","sources":["../../../../src/models/server/ISocketRouteProcessor.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IBaseRouteProcessor } from \"./IBaseRouteProcessor.js\";\nimport type { IHttpResponse } from \"../protocol/IHttpResponse.js\";\nimport type { ISocketServerRequest } from \"../protocol/ISocketServerRequest.js\";\nimport type { ISocketRoute } from \"../routes/ISocketRoute.js\";\n\n/**\n * The definition for a processor for handling socket routes.\n */\nexport interface ISocketRouteProcessor extends IBaseRouteProcessor<\n\tISocketRoute,\n\tISocketServerRequest\n> {\n\t/**\n\t * Process the connected event.\n\t * @param request The server request object containing the socket id and other parameters.\n\t * @param route The route being requested, if a matching one was found.\n\t * @param loggingComponentType The logging component type for the request.\n\t * @returns Promise that resolves when the request is processed.\n\t */\n\tconnected?(\n\t\trequest: ISocketServerRequest,\n\t\troute: ISocketRoute | undefined,\n\t\tloggingComponentType?: string\n\t): Promise<void>;\n\n\t/**\n\t * Process the disconnected event.\n\t * @param request The server request object containing the socket id and other parameters.\n\t * @param route The route being requested, if a matching one was found.\n\t * @param loggingComponentType The logging component type for the request.\n\t * @returns Promise that resolves when the request is processed.\n\t */\n\tdisconnected?(\n\t\trequest: ISocketServerRequest,\n\t\troute: ISocketRoute | undefined,\n\t\tloggingComponentType?: string\n\t): Promise<void>;\n\n\t/**\n\t * Process the REST request for the specified route.\n\t * @param request The server request object containing the socket id and other parameters.\n\t * @param response The response data to send if any.\n\t * @param route The route being requested, if a matching one was found.\n\t * @param processorState The state handed through the processors.\n\t * @param responseEmitter The function to emit a response.\n\t * @param loggingComponentType The logging component type for the request.\n\t * @returns Promise that resolves when the request is processed.\n\t */\n\tprocess?(\n\t\trequest: ISocketServerRequest,\n\t\tresponse: IHttpResponse,\n\t\troute: ISocketRoute | undefined,\n\t\tprocessorState: { [id: string]: unknown },\n\t\tresponseEmitter: (topic: string, response: IHttpResponse) => Promise<void>,\n\t\tloggingComponentType?: string\n\t): Promise<void>;\n}\n"]}

package/docs/changelog.md

@@ -1,4 +1,11 @@
-# @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)
 

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/interfaces/IWebServerOptions.md

@@ -10,12 +10,6 @@ Options for the web server.
 
 The port to bind the web server to.
 
-#### Default
-
-```ts
-3000
-```
-
 ***
 
 ### host?
@@ -24,12 +18,6 @@ The port to bind the web server to.
 
 The address to bind the web server to.
 
-#### Default
-
-```ts
-localhost
-```
-
 ***
 
 ### methods?
@@ -38,12 +26,6 @@ localhost
 
 The methods that the server accepts.
 
-#### Default
-
-```ts
-["GET", "PUT", "POST", "DELETE", "OPTIONS"]
-```
-
 ***
 
 ### allowedHeaders?
@@ -67,9 +49,3 @@ And additional exposed headers.
 > `optional` **corsOrigins**: `string` \| `string`[]
 
 The allowed CORS domains.
-
-#### Default
-
-```ts
-["*"]
-```

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@twin.org/api-models",
-	"version": "0.0.3-next.20",
-	"description": "Contains models and classes for use with APIs",
+	"version": "0.0.3-next.21",
+	"description": "Shared API contracts, route types, and response models used across services and clients.",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/twinfoundation/api.git",