@twin.org/api-models 0.9.1-next.2 → 0.9.1-next.3

package/dist/es/helpers/httpHeaderHelper.js

@@ -0,0 +1,126 @@
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import { GeneralError, Guards, Is, StringHelper } from "@twin.org/core";
+import { HeaderHelper, HeaderTypes, MimeTypes } from "@twin.org/web";
+import { HttpUrlHelper } from "./httpUrlHelper.js";
+/**
+ * Class to help with handling http headers.
+ */
+export class HttpHeaderHelper {
+    /**
+     * Runtime name for the class.
+     */
+    static CLASS_NAME = "HttpHeaderHelper";
+    /**
+     * Set the Link header with a next cursor relation when a cursor is present.
+     * @param headers The response headers to mutate.
+     * @param url The request URL used as the base for the link.
+     * @param publicOrigin The public origin to substitute into the URL, if any.
+     * @param cursor The cursor value; when undefined or empty the header is not set.
+     */
+    static buildCursor(headers, url, publicOrigin, cursor) {
+        if (Is.stringValue(cursor)) {
+            headers[HeaderTypes.Link] = HeaderHelper.createLinkHeader(HttpUrlHelper.replaceOrigin(url, publicOrigin), { cursor }, "next");
+        }
+    }
+    /**
+     * Set the Location header to the encoded ID, optionally placed within a base URL or template.
+     * When baseUrl contains a colon-prefixed placeholder (e.g. "/path1/:id/path2") the
+     * encoded ID is substituted at that position; otherwise it is appended.
+     * The base URL may be an absolute URL or a relative path. When omitted the bare
+     * encoded ID is used.
+     * @param headers The response headers to mutate.
+     * @param id The resource ID to encode and place.
+     * @param baseUrl The optional base URL, relative path, or URL template.
+     */
+    static buildId(headers, id, baseUrl) {
+        Guards.stringValue(HttpHeaderHelper.CLASS_NAME, "id", id);
+        const encodedId = encodeURIComponent(id);
+        if (Is.stringValue(baseUrl)) {
+            if (baseUrl.includes("/:")) {
+                headers[HeaderTypes.Location] = baseUrl.replace(/\/:[^/?#]+/, `/${encodedId}`);
+            }
+            else {
+                headers[HeaderTypes.Location] = `${StringHelper.trimTrailingSlashes(baseUrl)}/${encodedId}`;
+            }
+        }
+        else {
+            headers[HeaderTypes.Location] = encodedId;
+        }
+    }
+    /**
+     * Set the Content-Type header to JSON-LD or JSON depending on the request Accept header.
+     * Uses HeaderHelper.extractAccept which parses the Accept header per RFC 7231 and returns
+     * entries ordered by quality descending, preserving original order for equal q-values.
+     * @param headers The response headers to mutate.
+     * @param requestHeaders The request headers to inspect for the Accept value.
+     */
+    static buildJsonContentType(headers, requestHeaders) {
+        const accepted = HeaderHelper.extractAccept(requestHeaders);
+        let contentType = MimeTypes.Json;
+        if (Is.arrayValue(accepted)) {
+            for (const { mimeType } of accepted) {
+                if (mimeType === MimeTypes.JsonLd) {
+                    contentType = MimeTypes.JsonLd;
+                    break;
+                }
+                if (mimeType === MimeTypes.Json || mimeType === "application/*" || mimeType === "*/*") {
+                    break;
+                }
+            }
+        }
+        headers[HeaderTypes.ContentType] = contentType;
+    }
+    /**
+     * Extract the cursor from the Link header's next relation.
+     * @param headers The response headers to extract the cursor from.
+     * @returns The cursor value or undefined if not present.
+     */
+    static extractCursor(headers) {
+        return HeaderHelper.extractLinkHeaderRelation(headers?.[HeaderTypes.Link], "next")
+            ?.urlQueryParams?.cursor;
+    }
+    /**
+     * Extract the resource ID from the Location response header.
+     * Handles absolute URLs (http://host/path/:id, http://host/path/:id?foo=bar),
+     * relative paths (/segment/:id, ./segment/:id), and bare ID values.
+     * When a URL template such as "/path1/:id/path2" is supplied the ID is extracted
+     * from the segment position marked by the first colon-prefixed placeholder.
+     * Without a template the last path segment is returned.
+     * @param headers The response headers containing the Location header.
+     * @param template Optional URL template with a colon-prefixed placeholder marking the ID position, e.g. "/path1/:id/path2".
+     * @returns The extracted ID string.
+     * @throws GeneralError If the Location header is missing, the template has no placeholder, or the ID cannot be extracted.
+     */
+    static extractId(headers, template) {
+        const location = headers?.[HeaderTypes.Location];
+        if (!Is.stringValue(location)) {
+            throw new GeneralError(HttpHeaderHelper.CLASS_NAME, "locationMissing");
+        }
+        const withoutQuery = location.split("?")[0];
+        if (Is.stringValue(template)) {
+            const templateSegments = template.split("/").filter(s => s.length > 0);
+            const placeholderIndex = templateSegments.findIndex(s => s.startsWith(":"));
+            if (placeholderIndex === -1) {
+                throw new GeneralError(HttpHeaderHelper.CLASS_NAME, "templateNoPlaceholder");
+            }
+            let path = withoutQuery;
+            try {
+                path = new URL(withoutQuery).pathname;
+            }
+            catch { }
+            const locationSegments = path.split("/").filter(s => s.length > 0 && s !== ".");
+            const id = locationSegments[placeholderIndex];
+            if (!Is.stringValue(id)) {
+                throw new GeneralError(HttpHeaderHelper.CLASS_NAME, "idNotFound");
+            }
+            return decodeURIComponent(id);
+        }
+        const id = withoutQuery.includes("/") ? withoutQuery.split("/").pop() : withoutQuery;
+        if (!Is.stringValue(id)) {
+            throw new GeneralError(HttpHeaderHelper.CLASS_NAME, "idNotFound");
+        }
+        return decodeURIComponent(id);
+    }
+}
+//# sourceMappingURL=httpHeaderHelper.js.map

package/dist/es/helpers/httpHeaderHelper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"httpHeaderHelper.js","sourceRoot":"","sources":["../../../src/helpers/httpHeaderHelper.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { GeneralError, Guards, Is, StringHelper } from \"@twin.org/core\";\nimport { nameof } from \"@twin.org/nameof\";\nimport { HeaderHelper, HeaderTypes, MimeTypes, type IHttpHeaders } from \"@twin.org/web\";\nimport { HttpUrlHelper } from \"./httpUrlHelper.js\";\n\n/**\n * Class to help with handling http headers.\n */\nexport class HttpHeaderHelper {\n\t/**\n\t * Runtime name for the class.\n\t */\n\tpublic static readonly CLASS_NAME: string = nameof<HttpHeaderHelper>();\n\n\t/**\n\t * Set the Link header with a next cursor relation when a cursor is present.\n\t * @param headers The response headers to mutate.\n\t * @param url The request URL used as the base for the link.\n\t * @param publicOrigin The public origin to substitute into the URL, if any.\n\t * @param cursor The cursor value; when undefined or empty the header is not set.\n\t */\n\tpublic static buildCursor(\n\t\theaders: IHttpHeaders,\n\t\turl: string,\n\t\tpublicOrigin: string | undefined,\n\t\tcursor: string | undefined\n\t): asserts headers is IHttpHeaders & { [HeaderTypes.Link]: string | undefined } {\n\t\tif (Is.stringValue(cursor)) {\n\t\t\theaders[HeaderTypes.Link] = HeaderHelper.createLinkHeader(\n\t\t\t\tHttpUrlHelper.replaceOrigin(url, publicOrigin),\n\t\t\t\t{ cursor },\n\t\t\t\t\"next\"\n\t\t\t);\n\t\t}\n\t}\n\n\t/**\n\t * Set the Location header to the encoded ID, optionally placed within a base URL or template.\n\t * When baseUrl contains a colon-prefixed placeholder (e.g. \"/path1/:id/path2\") the\n\t * encoded ID is substituted at that position; otherwise it is appended.\n\t * The base URL may be an absolute URL or a relative path. When omitted the bare\n\t * encoded ID is used.\n\t * @param headers The response headers to mutate.\n\t * @param id The resource ID to encode and place.\n\t * @param baseUrl The optional base URL, relative path, or URL template.\n\t */\n\tpublic static buildId(\n\t\theaders: IHttpHeaders,\n\t\tid: string,\n\t\tbaseUrl?: string\n\t): asserts headers is IHttpHeaders & { [HeaderTypes.Location]: string } {\n\t\tGuards.stringValue(HttpHeaderHelper.CLASS_NAME, nameof(id), id);\n\t\tconst encodedId = encodeURIComponent(id);\n\t\tif (Is.stringValue(baseUrl)) {\n\t\t\tif (baseUrl.includes(\"/:\")) {\n\t\t\t\theaders[HeaderTypes.Location] = baseUrl.replace(/\\/:[^/?#]+/, `/${encodedId}`);\n\t\t\t} else {\n\t\t\t\theaders[HeaderTypes.Location] = `${StringHelper.trimTrailingSlashes(baseUrl)}/${encodedId}`;\n\t\t\t}\n\t\t} else {\n\t\t\theaders[HeaderTypes.Location] = encodedId;\n\t\t}\n\t}\n\n\t/**\n\t * Set the Content-Type header to JSON-LD or JSON depending on the request Accept header.\n\t * Uses HeaderHelper.extractAccept which parses the Accept header per RFC 7231 and returns\n\t * entries ordered by quality descending, preserving original order for equal q-values.\n\t * @param headers The response headers to mutate.\n\t * @param requestHeaders The request headers to inspect for the Accept value.\n\t */\n\tpublic static buildJsonContentType(\n\t\theaders: IHttpHeaders,\n\t\trequestHeaders?: IHttpHeaders\n\t): asserts headers is IHttpHeaders & {\n\t\t[HeaderTypes.ContentType]: typeof MimeTypes.JsonLd | typeof MimeTypes.Json;\n\t} {\n\t\tconst accepted = HeaderHelper.extractAccept(requestHeaders);\n\t\tlet contentType: string = MimeTypes.Json;\n\t\tif (Is.arrayValue(accepted)) {\n\t\t\tfor (const { mimeType } of accepted) {\n\t\t\t\tif (mimeType === MimeTypes.JsonLd) {\n\t\t\t\t\tcontentType = MimeTypes.JsonLd;\n\t\t\t\t\tbreak;\n\t\t\t\t}\n\t\t\t\tif (mimeType === MimeTypes.Json || mimeType === \"application/*\" || mimeType === \"*/*\") {\n\t\t\t\t\tbreak;\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\theaders[HeaderTypes.ContentType] = contentType;\n\t}\n\n\t/**\n\t * Extract the cursor from the Link header's next relation.\n\t * @param headers The response headers to extract the cursor from.\n\t * @returns The cursor value or undefined if not present.\n\t */\n\tpublic static extractCursor(headers?: IHttpHeaders): string | undefined {\n\t\treturn HeaderHelper.extractLinkHeaderRelation(headers?.[HeaderTypes.Link], \"next\")\n\t\t\t?.urlQueryParams?.cursor;\n\t}\n\n\t/**\n\t * Extract the resource ID from the Location response header.\n\t * Handles absolute URLs (http://host/path/:id, http://host/path/:id?foo=bar),\n\t * relative paths (/segment/:id, ./segment/:id), and bare ID values.\n\t * When a URL template such as \"/path1/:id/path2\" is supplied the ID is extracted\n\t * from the segment position marked by the first colon-prefixed placeholder.\n\t * Without a template the last path segment is returned.\n\t * @param headers The response headers containing the Location header.\n\t * @param template Optional URL template with a colon-prefixed placeholder marking the ID position, e.g. \"/path1/:id/path2\".\n\t * @returns The extracted ID string.\n\t * @throws GeneralError If the Location header is missing, the template has no placeholder, or the ID cannot be extracted.\n\t */\n\tpublic static extractId(headers?: IHttpHeaders, template?: string): string {\n\t\tconst location = headers?.[HeaderTypes.Location];\n\t\tif (!Is.stringValue(location)) {\n\t\t\tthrow new GeneralError(HttpHeaderHelper.CLASS_NAME, \"locationMissing\");\n\t\t}\n\n\t\tconst withoutQuery = location.split(\"?\")[0];\n\n\t\tif (Is.stringValue(template)) {\n\t\t\tconst templateSegments = template.split(\"/\").filter(s => s.length > 0);\n\t\t\tconst placeholderIndex = templateSegments.findIndex(s => s.startsWith(\":\"));\n\t\t\tif (placeholderIndex === -1) {\n\t\t\t\tthrow new GeneralError(HttpHeaderHelper.CLASS_NAME, \"templateNoPlaceholder\");\n\t\t\t}\n\n\t\t\tlet path = withoutQuery;\n\t\t\ttry {\n\t\t\t\tpath = new URL(withoutQuery).pathname;\n\t\t\t} catch {}\n\n\t\t\tconst locationSegments = path.split(\"/\").filter(s => s.length > 0 && s !== \".\");\n\t\t\tconst id = locationSegments[placeholderIndex];\n\n\t\t\tif (!Is.stringValue(id)) {\n\t\t\t\tthrow new GeneralError(HttpHeaderHelper.CLASS_NAME, \"idNotFound\");\n\t\t\t}\n\t\t\treturn decodeURIComponent(id);\n\t\t}\n\n\t\tconst id = withoutQuery.includes(\"/\") ? withoutQuery.split(\"/\").pop() : withoutQuery;\n\n\t\tif (!Is.stringValue(id)) {\n\t\t\tthrow new GeneralError(HttpHeaderHelper.CLASS_NAME, \"idNotFound\");\n\t\t}\n\t\treturn decodeURIComponent(id);\n\t}\n}\n"]}

package/dist/es/index.js

@@ -6,6 +6,7 @@ export * from "./factories/mimeTypeProcessorFactory.js";
 export * from "./factories/restRouteProcessorFactory.js";
 export * from "./factories/socketRouteProcessorFactory.js";
 export * from "./helpers/httpErrorHelper.js";
+export * from "./helpers/httpHeaderHelper.js";
 export * from "./helpers/httpParameterHelper.js";
 export * from "./helpers/httpUrlHelper.js";
 export * from "./models/api/IServerFavIconResponse.js";

package/dist/es/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,kCAAkC,CAAC;AACjD,cAAc,yCAAyC,CAAC;AACxD,cAAc,0CAA0C,CAAC;AACzD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,8BAA8B,CAAC;AAC7C,cAAc,kCAAkC,CAAC;AACjD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,wCAAwC,CAAC;AACvD,cAAc,uCAAuC,CAAC;AACtD,cAAc,qCAAqC,CAAC;AACpD,cAAc,sCAAsC,CAAC;AACrD,cAAc,uCAAuC,CAAC;AACtD,cAAc,qCAAqC,CAAC;AACpD,cAAc,qCAAqC,CAAC;AACpD,cAAc,0CAA0C,CAAC;AACzD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,+BAA+B,CAAC;AAC9C,cAAc,mCAAmC,CAAC;AAClD,cAAc,0CAA0C,CAAC;AACzD,cAAc,6CAA6C,CAAC;AAC5D,cAAc,wCAAwC,CAAC;AACvD,cAAc,oCAAoC,CAAC;AACnD,cAAc,yCAAyC,CAAC;AACxD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,2CAA2C,CAAC;AAC1D,cAAc,wCAAwC,CAAC;AACvD,cAAc,kDAAkD,CAAC;AACjE,cAAc,gDAAgD,CAAC;AAC/D,cAAc,iDAAiD,CAAC;AAChE,cAAc,2DAA2D,CAAC;AAC1E,cAAc,gDAAgD,CAAC;AAC/D,cAAc,sDAAsD,CAAC;AACrE,cAAc,uDAAuD,CAAC;AACtE,cAAc,oDAAoD,CAAC;AACnE,cAAc,2DAA2D,CAAC;AAC1E,cAAc,iDAAiD,CAAC;AAChE,cAAc,gDAAgD,CAAC;AAC/D,cAAc,kDAAkD,CAAC;AACjE,cAAc,2CAA2C,CAAC;AAC1D,cAAc,+BAA+B,CAAC;AAC9C,cAAc,yCAAyC,CAAC;AACxD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,yCAAyC,CAAC;AACxD,cAAc,sCAAsC,CAAC;AACrD,cAAc,6CAA6C,CAAC;AAC5D,cAAc,wDAAwD,CAAC;AACvE,cAAc,8CAA8C,CAAC;AAC7D,cAAc,8CAA8C,CAAC;AAC7D,cAAc,iCAAiC,CAAC;AAChD,cAAc,2CAA2C,CAAC;AAC1D,cAAc,yBAAyB,CAAC;AACxC,cAAc,wCAAwC,CAAC;AACvD,cAAc,uCAAuC,CAAC;AACtD,cAAc,wCAAwC,CAAC;AACvD,cAAc,0CAA0C,CAAC;AACzD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,sCAAsC,CAAC;AACrD,cAAc,uCAAuC,CAAC;AACtD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,yCAAyC,CAAC;AACxD,cAAc,kCAAkC,CAAC;AACjD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,4CAA4C,CAAC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nexport * from \"./errors/forbiddenError.js\";\nexport * from \"./errors/tooManyRequestsError.js\";\nexport * from \"./factories/mimeTypeProcessorFactory.js\";\nexport * from \"./factories/restRouteProcessorFactory.js\";\nexport * from \"./factories/socketRouteProcessorFactory.js\";\nexport * from \"./helpers/httpErrorHelper.js\";\nexport * from \"./helpers/httpParameterHelper.js\";\nexport * from \"./helpers/httpUrlHelper.js\";\nexport * from \"./models/api/IServerFavIconResponse.js\";\nexport * from \"./models/api/IServerHealthResponse.js\";\nexport * from \"./models/api/IServerInfoResponse.js\";\nexport * from \"./models/api/IServerLivezResponse.js\";\nexport * from \"./models/api/IServerReadyzResponse.js\";\nexport * from \"./models/api/IServerRootResponse.js\";\nexport * from \"./models/api/IServerSpecResponse.js\";\nexport * from \"./models/config/IBaseRestClientConfig.js\";\nexport * from \"./models/config/IBaseSocketClientConfig.js\";\nexport * from \"./models/httpContextIdKeys.js\";\nexport * from \"./models/protocol/IHttpRequest.js\";\nexport * from \"./models/protocol/IHttpRequestContext.js\";\nexport * from \"./models/protocol/IHttpRequestPathParams.js\";\nexport * from \"./models/protocol/IHttpRequestQuery.js\";\nexport * from \"./models/protocol/IHttpResponse.js\";\nexport * from \"./models/protocol/IHttpServerRequest.js\";\nexport * from \"./models/protocol/ISocketRequestContext.js\";\nexport * from \"./models/protocol/ISocketServerRequest.js\";\nexport * from \"./models/requests/INoContentRequest.js\";\nexport * from \"./models/responses/errors/IBadRequestResponse.js\";\nexport * from \"./models/responses/errors/IConflictResponse.js\";\nexport * from \"./models/responses/errors/IForbiddenResponse.js\";\nexport * from \"./models/responses/errors/IInternalServerErrorResponse.js\";\nexport * from \"./models/responses/errors/INotFoundResponse.js\";\nexport * from \"./models/responses/errors/INotImplementedResponse.js\";\nexport * from \"./models/responses/errors/ITooManyRequestsResponse.js\";\nexport * from \"./models/responses/errors/IUnauthorizedResponse.js\";\nexport * from \"./models/responses/errors/IUnprocessableEntityResponse.js\";\nexport * from \"./models/responses/success/IAcceptedResponse.js\";\nexport * from \"./models/responses/success/ICreatedResponse.js\";\nexport * from \"./models/responses/success/INoContentResponse.js\";\nexport * from \"./models/responses/success/IOkResponse.js\";\nexport * from \"./models/routes/IBaseRoute.js\";\nexport * from \"./models/routes/IBaseRouteEntryPoint.js\";\nexport * from \"./models/routes/IRestRoute.js\";\nexport * from \"./models/routes/IRestRouteEntryPoint.js\";\nexport * from \"./models/routes/IRestRouteExample.js\";\nexport * from \"./models/routes/IRestRouteRequestExample.js\";\nexport * from \"./models/routes/IRestRouteResponseAttachmentOptions.js\";\nexport * from \"./models/routes/IRestRouteResponseExample.js\";\nexport * from \"./models/routes/IRestRouteResponseOptions.js\";\nexport * from \"./models/routes/ISocketRoute.js\";\nexport * from \"./models/routes/ISocketRouteEntryPoint.js\";\nexport * from \"./models/routes/ITag.js\";\nexport * from \"./models/server/IBaseRouteProcessor.js\";\nexport * from \"./models/server/IMimeTypeProcessor.js\";\nexport * from \"./models/server/IRestRouteProcessor.js\";\nexport * from \"./models/server/ISocketRouteProcessor.js\";\nexport * from \"./models/server/IWebServer.js\";\nexport * from \"./models/server/IWebServerOptions.js\";\nexport * from \"./models/services/IHealthComponent.js\";\nexport * from \"./models/services/IInformationComponent.js\";\nexport * from \"./models/services/IPlatformComponent.js\";\nexport * from \"./models/services/IServerInfo.js\";\nexport * from \"./models/services/ITenant.js\";\nexport * from \"./models/services/ITenantAdminComponent.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,kCAAkC,CAAC;AACjD,cAAc,yCAAyC,CAAC;AACxD,cAAc,0CAA0C,CAAC;AACzD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,8BAA8B,CAAC;AAC7C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,kCAAkC,CAAC;AACjD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,wCAAwC,CAAC;AACvD,cAAc,uCAAuC,CAAC;AACtD,cAAc,qCAAqC,CAAC;AACpD,cAAc,sCAAsC,CAAC;AACrD,cAAc,uCAAuC,CAAC;AACtD,cAAc,qCAAqC,CAAC;AACpD,cAAc,qCAAqC,CAAC;AACpD,cAAc,0CAA0C,CAAC;AACzD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,+BAA+B,CAAC;AAC9C,cAAc,mCAAmC,CAAC;AAClD,cAAc,0CAA0C,CAAC;AACzD,cAAc,6CAA6C,CAAC;AAC5D,cAAc,wCAAwC,CAAC;AACvD,cAAc,oCAAoC,CAAC;AACnD,cAAc,yCAAyC,CAAC;AACxD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,2CAA2C,CAAC;AAC1D,cAAc,wCAAwC,CAAC;AACvD,cAAc,kDAAkD,CAAC;AACjE,cAAc,gDAAgD,CAAC;AAC/D,cAAc,iDAAiD,CAAC;AAChE,cAAc,2DAA2D,CAAC;AAC1E,cAAc,gDAAgD,CAAC;AAC/D,cAAc,sDAAsD,CAAC;AACrE,cAAc,uDAAuD,CAAC;AACtE,cAAc,oDAAoD,CAAC;AACnE,cAAc,2DAA2D,CAAC;AAC1E,cAAc,iDAAiD,CAAC;AAChE,cAAc,gDAAgD,CAAC;AAC/D,cAAc,kDAAkD,CAAC;AACjE,cAAc,2CAA2C,CAAC;AAC1D,cAAc,+BAA+B,CAAC;AAC9C,cAAc,yCAAyC,CAAC;AACxD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,yCAAyC,CAAC;AACxD,cAAc,sCAAsC,CAAC;AACrD,cAAc,6CAA6C,CAAC;AAC5D,cAAc,wDAAwD,CAAC;AACvE,cAAc,8CAA8C,CAAC;AAC7D,cAAc,8CAA8C,CAAC;AAC7D,cAAc,iCAAiC,CAAC;AAChD,cAAc,2CAA2C,CAAC;AAC1D,cAAc,yBAAyB,CAAC;AACxC,cAAc,wCAAwC,CAAC;AACvD,cAAc,uCAAuC,CAAC;AACtD,cAAc,wCAAwC,CAAC;AACvD,cAAc,0CAA0C,CAAC;AACzD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,sCAAsC,CAAC;AACrD,cAAc,uCAAuC,CAAC;AACtD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,yCAAyC,CAAC;AACxD,cAAc,kCAAkC,CAAC;AACjD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,4CAA4C,CAAC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nexport * from \"./errors/forbiddenError.js\";\nexport * from \"./errors/tooManyRequestsError.js\";\nexport * from \"./factories/mimeTypeProcessorFactory.js\";\nexport * from \"./factories/restRouteProcessorFactory.js\";\nexport * from \"./factories/socketRouteProcessorFactory.js\";\nexport * from \"./helpers/httpErrorHelper.js\";\nexport * from \"./helpers/httpHeaderHelper.js\";\nexport * from \"./helpers/httpParameterHelper.js\";\nexport * from \"./helpers/httpUrlHelper.js\";\nexport * from \"./models/api/IServerFavIconResponse.js\";\nexport * from \"./models/api/IServerHealthResponse.js\";\nexport * from \"./models/api/IServerInfoResponse.js\";\nexport * from \"./models/api/IServerLivezResponse.js\";\nexport * from \"./models/api/IServerReadyzResponse.js\";\nexport * from \"./models/api/IServerRootResponse.js\";\nexport * from \"./models/api/IServerSpecResponse.js\";\nexport * from \"./models/config/IBaseRestClientConfig.js\";\nexport * from \"./models/config/IBaseSocketClientConfig.js\";\nexport * from \"./models/httpContextIdKeys.js\";\nexport * from \"./models/protocol/IHttpRequest.js\";\nexport * from \"./models/protocol/IHttpRequestContext.js\";\nexport * from \"./models/protocol/IHttpRequestPathParams.js\";\nexport * from \"./models/protocol/IHttpRequestQuery.js\";\nexport * from \"./models/protocol/IHttpResponse.js\";\nexport * from \"./models/protocol/IHttpServerRequest.js\";\nexport * from \"./models/protocol/ISocketRequestContext.js\";\nexport * from \"./models/protocol/ISocketServerRequest.js\";\nexport * from \"./models/requests/INoContentRequest.js\";\nexport * from \"./models/responses/errors/IBadRequestResponse.js\";\nexport * from \"./models/responses/errors/IConflictResponse.js\";\nexport * from \"./models/responses/errors/IForbiddenResponse.js\";\nexport * from \"./models/responses/errors/IInternalServerErrorResponse.js\";\nexport * from \"./models/responses/errors/INotFoundResponse.js\";\nexport * from \"./models/responses/errors/INotImplementedResponse.js\";\nexport * from \"./models/responses/errors/ITooManyRequestsResponse.js\";\nexport * from \"./models/responses/errors/IUnauthorizedResponse.js\";\nexport * from \"./models/responses/errors/IUnprocessableEntityResponse.js\";\nexport * from \"./models/responses/success/IAcceptedResponse.js\";\nexport * from \"./models/responses/success/ICreatedResponse.js\";\nexport * from \"./models/responses/success/INoContentResponse.js\";\nexport * from \"./models/responses/success/IOkResponse.js\";\nexport * from \"./models/routes/IBaseRoute.js\";\nexport * from \"./models/routes/IBaseRouteEntryPoint.js\";\nexport * from \"./models/routes/IRestRoute.js\";\nexport * from \"./models/routes/IRestRouteEntryPoint.js\";\nexport * from \"./models/routes/IRestRouteExample.js\";\nexport * from \"./models/routes/IRestRouteRequestExample.js\";\nexport * from \"./models/routes/IRestRouteResponseAttachmentOptions.js\";\nexport * from \"./models/routes/IRestRouteResponseExample.js\";\nexport * from \"./models/routes/IRestRouteResponseOptions.js\";\nexport * from \"./models/routes/ISocketRoute.js\";\nexport * from \"./models/routes/ISocketRouteEntryPoint.js\";\nexport * from \"./models/routes/ITag.js\";\nexport * from \"./models/server/IBaseRouteProcessor.js\";\nexport * from \"./models/server/IMimeTypeProcessor.js\";\nexport * from \"./models/server/IRestRouteProcessor.js\";\nexport * from \"./models/server/ISocketRouteProcessor.js\";\nexport * from \"./models/server/IWebServer.js\";\nexport * from \"./models/server/IWebServerOptions.js\";\nexport * from \"./models/services/IHealthComponent.js\";\nexport * from \"./models/services/IInformationComponent.js\";\nexport * from \"./models/services/IPlatformComponent.js\";\nexport * from \"./models/services/IServerInfo.js\";\nexport * from \"./models/services/ITenant.js\";\nexport * from \"./models/services/ITenantAdminComponent.js\";\n"]}

package/dist/types/helpers/httpHeaderHelper.d.ts

@@ -0,0 +1,62 @@
+import { HeaderTypes, MimeTypes, type IHttpHeaders } from "@twin.org/web";
+/**
+ * Class to help with handling http headers.
+ */
+export declare class HttpHeaderHelper {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * Set the Link header with a next cursor relation when a cursor is present.
+     * @param headers The response headers to mutate.
+     * @param url The request URL used as the base for the link.
+     * @param publicOrigin The public origin to substitute into the URL, if any.
+     * @param cursor The cursor value; when undefined or empty the header is not set.
+     */
+    static buildCursor(headers: IHttpHeaders, url: string, publicOrigin: string | undefined, cursor: string | undefined): asserts headers is IHttpHeaders & {
+        [HeaderTypes.Link]: string | undefined;
+    };
+    /**
+     * Set the Location header to the encoded ID, optionally placed within a base URL or template.
+     * When baseUrl contains a colon-prefixed placeholder (e.g. "/path1/:id/path2") the
+     * encoded ID is substituted at that position; otherwise it is appended.
+     * The base URL may be an absolute URL or a relative path. When omitted the bare
+     * encoded ID is used.
+     * @param headers The response headers to mutate.
+     * @param id The resource ID to encode and place.
+     * @param baseUrl The optional base URL, relative path, or URL template.
+     */
+    static buildId(headers: IHttpHeaders, id: string, baseUrl?: string): asserts headers is IHttpHeaders & {
+        [HeaderTypes.Location]: string;
+    };
+    /**
+     * Set the Content-Type header to JSON-LD or JSON depending on the request Accept header.
+     * Uses HeaderHelper.extractAccept which parses the Accept header per RFC 7231 and returns
+     * entries ordered by quality descending, preserving original order for equal q-values.
+     * @param headers The response headers to mutate.
+     * @param requestHeaders The request headers to inspect for the Accept value.
+     */
+    static buildJsonContentType(headers: IHttpHeaders, requestHeaders?: IHttpHeaders): asserts headers is IHttpHeaders & {
+        [HeaderTypes.ContentType]: typeof MimeTypes.JsonLd | typeof MimeTypes.Json;
+    };
+    /**
+     * Extract the cursor from the Link header's next relation.
+     * @param headers The response headers to extract the cursor from.
+     * @returns The cursor value or undefined if not present.
+     */
+    static extractCursor(headers?: IHttpHeaders): string | undefined;
+    /**
+     * Extract the resource ID from the Location response header.
+     * Handles absolute URLs (http://host/path/:id, http://host/path/:id?foo=bar),
+     * relative paths (/segment/:id, ./segment/:id), and bare ID values.
+     * When a URL template such as "/path1/:id/path2" is supplied the ID is extracted
+     * from the segment position marked by the first colon-prefixed placeholder.
+     * Without a template the last path segment is returned.
+     * @param headers The response headers containing the Location header.
+     * @param template Optional URL template with a colon-prefixed placeholder marking the ID position, e.g. "/path1/:id/path2".
+     * @returns The extracted ID string.
+     * @throws GeneralError If the Location header is missing, the template has no placeholder, or the ID cannot be extracted.
+     */
+    static extractId(headers?: IHttpHeaders, template?: string): string;
+}

package/dist/types/index.d.ts

@@ -4,6 +4,7 @@ export * from "./factories/mimeTypeProcessorFactory.js";
 export * from "./factories/restRouteProcessorFactory.js";
 export * from "./factories/socketRouteProcessorFactory.js";
 export * from "./helpers/httpErrorHelper.js";
+export * from "./helpers/httpHeaderHelper.js";
 export * from "./helpers/httpParameterHelper.js";
 export * from "./helpers/httpUrlHelper.js";
 export * from "./models/api/IServerFavIconResponse.js";

package/docs/changelog.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.9.1-next.3](https://github.com/iotaledger/twin-api/compare/api-models-v0.9.1-next.2...api-models-v0.9.1-next.3) (2026-06-29)
+
+
+### Features
+
+* enhanced rest handling ([#208](https://github.com/iotaledger/twin-api/issues/208)) ([99d5f3f](https://github.com/iotaledger/twin-api/commit/99d5f3f96d262e57828d98d3f3b1e3da8a863378))
+
 ## [0.9.1-next.2](https://github.com/iotaledger/twin-api/compare/api-models-v0.9.1-next.1...api-models-v0.9.1-next.2) (2026-06-26)
 
 

package/docs/reference/classes/HttpHeaderHelper.md

@@ -0,0 +1,182 @@
+# Class: HttpHeaderHelper
+
+Class to help with handling http headers.
+
+## Constructors
+
+### Constructor
+
+> **new HttpHeaderHelper**(): `HttpHeaderHelper`
+
+#### Returns
+
+`HttpHeaderHelper`
+
+## Properties
+
+### CLASS\_NAME {#class_name}
+
+> `readonly` `static` **CLASS\_NAME**: `string`
+
+Runtime name for the class.
+
+## Methods
+
+### buildCursor() {#buildcursor}
+
+> `static` **buildCursor**(`headers`, `url`, `publicOrigin`, `cursor`): asserts headers is IHttpHeaders & \{ link: string \| undefined \}
+
+Set the Link header with a next cursor relation when a cursor is present.
+
+#### Parameters
+
+##### headers
+
+`IHttpHeaders`
+
+The response headers to mutate.
+
+##### url
+
+`string`
+
+The request URL used as the base for the link.
+
+##### publicOrigin
+
+`string` \| `undefined`
+
+The public origin to substitute into the URL, if any.
+
+##### cursor
+
+`string` \| `undefined`
+
+The cursor value; when undefined or empty the header is not set.
+
+#### Returns
+
+asserts headers is IHttpHeaders & \{ link: string \| undefined \}
+
+***
+
+### buildId() {#buildid}
+
+> `static` **buildId**(`headers`, `id`, `baseUrl?`): `asserts headers is IHttpHeaders & { location: string }`
+
+Set the Location header to the encoded ID, optionally placed within a base URL or template.
+When baseUrl contains a colon-prefixed placeholder (e.g. "/path1/:id/path2") the
+encoded ID is substituted at that position; otherwise it is appended.
+The base URL may be an absolute URL or a relative path. When omitted the bare
+encoded ID is used.
+
+#### Parameters
+
+##### headers
+
+`IHttpHeaders`
+
+The response headers to mutate.
+
+##### id
+
+`string`
+
+The resource ID to encode and place.
+
+##### baseUrl?
+
+`string`
+
+The optional base URL, relative path, or URL template.
+
+#### Returns
+
+`asserts headers is IHttpHeaders & { location: string }`
+
+***
+
+### buildJsonContentType() {#buildjsoncontenttype}
+
+> `static` **buildJsonContentType**(`headers`, `requestHeaders?`): asserts headers is IHttpHeaders & \{ content-type: "application/json" \| "application/ld+json" \}
+
+Set the Content-Type header to JSON-LD or JSON depending on the request Accept header.
+Uses HeaderHelper.extractAccept which parses the Accept header per RFC 7231 and returns
+entries ordered by quality descending, preserving original order for equal q-values.
+
+#### Parameters
+
+##### headers
+
+`IHttpHeaders`
+
+The response headers to mutate.
+
+##### requestHeaders?
+
+`IHttpHeaders`
+
+The request headers to inspect for the Accept value.
+
+#### Returns
+
+asserts headers is IHttpHeaders & \{ content-type: "application/json" \| "application/ld+json" \}
+
+***
+
+### extractCursor() {#extractcursor}
+
+> `static` **extractCursor**(`headers?`): `string` \| `undefined`
+
+Extract the cursor from the Link header's next relation.
+
+#### Parameters
+
+##### headers?
+
+`IHttpHeaders`
+
+The response headers to extract the cursor from.
+
+#### Returns
+
+`string` \| `undefined`
+
+The cursor value or undefined if not present.
+
+***
+
+### extractId() {#extractid}
+
+> `static` **extractId**(`headers?`, `template?`): `string`
+
+Extract the resource ID from the Location response header.
+Handles absolute URLs (http://host/path/:id, http://host/path/:id?foo=bar),
+relative paths (/segment/:id, ./segment/:id), and bare ID values.
+When a URL template such as "/path1/:id/path2" is supplied the ID is extracted
+from the segment position marked by the first colon-prefixed placeholder.
+Without a template the last path segment is returned.
+
+#### Parameters
+
+##### headers?
+
+`IHttpHeaders`
+
+The response headers containing the Location header.
+
+##### template?
+
+`string`
+
+Optional URL template with a colon-prefixed placeholder marking the ID position, e.g. "/path1/:id/path2".
+
+#### Returns
+
+`string`
+
+The extracted ID string.
+
+#### Throws
+
+GeneralError If the Location header is missing, the template has no placeholder, or the ID cannot be extracted.

package/docs/reference/index.md

@@ -5,6 +5,7 @@
 - [ForbiddenError](classes/ForbiddenError.md)
 - [TooManyRequestsError](classes/TooManyRequestsError.md)
 - [HttpErrorHelper](classes/HttpErrorHelper.md)
+- [HttpHeaderHelper](classes/HttpHeaderHelper.md)
 - [HttpParameterHelper](classes/HttpParameterHelper.md)
 - [HttpUrlHelper](classes/HttpUrlHelper.md)
 

package/locales/en.json

@@ -1 +1,9 @@
-{}
+{
+	"error": {
+		"httpHeaderHelper": {
+			"locationMissing": "The Location response header is missing or empty",
+			"idNotFound": "The resource ID could not be extracted from the Location header",
+			"templateNoPlaceholder": "The URL template contains no colon-prefixed placeholder segment"
+		}
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twin.org/api-models",
-	"version": "0.9.1-next.2",
+	"version": "0.9.1-next.3",
 	"description": "Shared API contracts, route types, and response models used across services and clients.",
 	"repository": {
 		"type": "git",