@twin.org/api-models 0.0.3-next.28 → 0.0.3-next.29

package/dist/es/helpers/httpUrlHelper.js

@@ -67,6 +67,19 @@ export class HttpUrlHelper {
             return `${StringHelper.trimTrailingSlashes(origin)}/${StringHelper.trimLeadingSlashes(pathAndSearch)}`;
         }
     }
+    /**
+     * 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.
+     * @see https://datatracker.ietf.org/doc/html/rfc3986#section-3.3
+     * @param segment The raw path segment value to encode.
+     * @returns The percent-encoded path segment.
+     */
+    static encodeUriPathSegment(segment) {
+        // RFC 3986 §3.3: only encode characters outside the allowed path segment set.
+        // Allowed: unreserved (A-Za-z0-9 - . _ ~), sub-delimiters (! $ & ' ( ) * + , ; =), and : @
+        return segment.replace(/[^\w!$&'()*+,.:;=@~-]/g, ch => encodeURIComponent(ch));
+    }
     /**
      * Replace the origin in the url.
      * @param url The url to replace the origin in.

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

@@ -1 +1 @@
-{"version":3,"file":"httpUrlHelper.js","sourceRoot":"","sources":["../../../src/helpers/httpUrlHelper.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,OAAO,EAAE,EAAE,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAElD;;GAEG;AACH,MAAM,OAAO,aAAa;IACzB;;;;;OAKG;IACI,MAAM,CAAC,aAAa,CAAC,GAAW;QACtC,IAAI,CAAC;YACJ,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;YAClC,OAAO,YAAY,CAAC,MAAM,CAAC;QAC5B,CAAC;QAAC,MAAM,CAAC,CAAA,CAAC;IACX,CAAC;IAED;;;;;OAKG;IACI,MAAM,CAAC,WAAW,CAAC,GAAW;QACpC,IAAI,CAAC;YACJ,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;YAClC,OAAO,YAAY,CAAC,QAAQ,CAAC;QAC9B,CAAC;QAAC,MAAM,CAAC,CAAA,CAAC;IACX,CAAC;IAED;;;;;OAKG;IACI,MAAM,CAAC,aAAa,CAAC,GAAW;QACtC,IAAI,CAAC;YACJ,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;YAClC,OAAO,YAAY,CAAC,MAAM,CAAC;QAC5B,CAAC;QAAC,MAAM,CAAC,CAAA,CAAC;IACX,CAAC;IAED;;;;OAIG;IACI,MAAM,CAAC,oBAAoB,CAAC,GAAW;QAC7C,IAAI,CAAC;YACJ,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;YAClC,OAAO,GAAG,YAAY,CAAC,QAAQ,GAAG,YAAY,CAAC,MAAM,EAAE,CAAC;QACzD,CAAC;QAAC,MAAM,CAAC,CAAA,CAAC;IACX,CAAC;IAED;;;;;OAKG;IACI,MAAM,CAAC,YAAY,CAAC,MAAc,EAAE,aAAqB;QAC/D,IAAI,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC;YACnD,OAAO,GAAG,YAAY,CAAC,mBAAmB,CAAC,MAAM,CAAC,IAAI,YAAY,CAAC,kBAAkB,CAAC,aAAa,CAAC,EAAE,CAAC;QACxG,CAAC;IACF,CAAC;IAED;;;;;OAKG;IACI,MAAM,CAAC,aAAa,CAAC,GAAW,EAAE,SAAkB;QAC1D,IAAI,CAAC,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,WAAW,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YACzF,OAAO,GAAG,CAAC;QACZ,CAAC;QAED,IAAI,CAAC;YACJ,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,qBAAqB,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YAClF,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,CAAC;YACxC,SAAS,CAAC,QAAQ,GAAG,YAAY,CAAC,QAAQ,CAAC;YAC3C,SAAS,CAAC,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC;YACnC,SAAS,CAAC,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC;YACnC,OAAO,SAAS,CAAC,QAAQ,EAAE,CAAC;QAC7B,CAAC;QAAC,MAAM,CAAC,CAAA,CAAC;QAEV,OAAO,GAAG,CAAC;IACZ,CAAC;CACD","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { Is, StringHelper } from \"@twin.org/core\";\n\n/**\n * Class to help with handling http URLs.\n */\nexport class HttpUrlHelper {\n\t/**\n\t * Extract the origin from the url which includes protocol,host,port.\n\t * @see https://developer.mozilla.org/en-US/docs/Web/API/URL/origin\n\t * @param url The url to extract the origin from.\n\t * @returns The extracted origin.\n\t */\n\tpublic static extractOrigin(url: string): string | undefined {\n\t\ttry {\n\t\t\tconst convertedUrl = new URL(url);\n\t\t\treturn convertedUrl.origin;\n\t\t} catch {}\n\t}\n\n\t/**\n\t * Extract the path from the url.\n\t * @see https://developer.mozilla.org/en-US/docs/Web/API/URL/pathname\n\t * @param url The url to extract the path from.\n\t * @returns The extracted path.\n\t */\n\tpublic static extractPath(url: string): string | undefined {\n\t\ttry {\n\t\t\tconst convertedUrl = new URL(url);\n\t\t\treturn convertedUrl.pathname;\n\t\t} catch {}\n\t}\n\n\t/**\n\t * Extract the search from the url.\n\t * @see https://developer.mozilla.org/en-US/docs/Web/API/URL/search\n\t * @param url The url to extract the search from.\n\t * @returns The extracted search.\n\t */\n\tpublic static extractSearch(url: string): string | undefined {\n\t\ttry {\n\t\t\tconst convertedUrl = new URL(url);\n\t\t\treturn convertedUrl.search;\n\t\t} catch {}\n\t}\n\n\t/**\n\t * Extract the path and search from the url.\n\t * @param url The url to extract the path and search from.\n\t * @returns The extracted path and search.\n\t */\n\tpublic static extractPathAndSearch(url: string): string | undefined {\n\t\ttry {\n\t\t\tconst convertedUrl = new URL(url);\n\t\t\treturn `${convertedUrl.pathname}${convertedUrl.search}`;\n\t\t} catch {}\n\t}\n\n\t/**\n\t * Combine the urls parts.\n\t * @param origin The origin to combine.\n\t * @param pathAndSearch The path and search to combine.\n\t * @returns The combined parts.\n\t */\n\tpublic static combineParts(origin: string, pathAndSearch: string): string | undefined {\n\t\tif (Is.string(origin) && Is.string(pathAndSearch)) {\n\t\t\treturn `${StringHelper.trimTrailingSlashes(origin)}/${StringHelper.trimLeadingSlashes(pathAndSearch)}`;\n\t\t}\n\t}\n\n\t/**\n\t * Replace the origin in the url.\n\t * @param url The url to replace the origin in.\n\t * @param newOrigin The new origin to use.\n\t * @returns The url with the replaced origin.\n\t */\n\tpublic static replaceOrigin(url: string, newOrigin?: string): string {\n\t\tif (!Is.stringValue(url) || !Is.stringValue(newOrigin) || !newOrigin.startsWith(\"http\")) {\n\t\t\treturn url;\n\t\t}\n\n\t\ttry {\n\t\t\tconst parsedUrl = new URL(url.startsWith(\"/\") ? `http://placeholder${url}` : url);\n\t\t\tconst newParsedUrl = new URL(newOrigin);\n\t\t\tparsedUrl.protocol = newParsedUrl.protocol;\n\t\t\tparsedUrl.host = newParsedUrl.host;\n\t\t\tparsedUrl.port = newParsedUrl.port;\n\t\t\treturn parsedUrl.toString();\n\t\t} catch {}\n\n\t\treturn url;\n\t}\n}\n"]}
+{"version":3,"file":"httpUrlHelper.js","sourceRoot":"","sources":["../../../src/helpers/httpUrlHelper.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,OAAO,EAAE,EAAE,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAElD;;GAEG;AACH,MAAM,OAAO,aAAa;IACzB;;;;;OAKG;IACI,MAAM,CAAC,aAAa,CAAC,GAAW;QACtC,IAAI,CAAC;YACJ,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;YAClC,OAAO,YAAY,CAAC,MAAM,CAAC;QAC5B,CAAC;QAAC,MAAM,CAAC,CAAA,CAAC;IACX,CAAC;IAED;;;;;OAKG;IACI,MAAM,CAAC,WAAW,CAAC,GAAW;QACpC,IAAI,CAAC;YACJ,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;YAClC,OAAO,YAAY,CAAC,QAAQ,CAAC;QAC9B,CAAC;QAAC,MAAM,CAAC,CAAA,CAAC;IACX,CAAC;IAED;;;;;OAKG;IACI,MAAM,CAAC,aAAa,CAAC,GAAW;QACtC,IAAI,CAAC;YACJ,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;YAClC,OAAO,YAAY,CAAC,MAAM,CAAC;QAC5B,CAAC;QAAC,MAAM,CAAC,CAAA,CAAC;IACX,CAAC;IAED;;;;OAIG;IACI,MAAM,CAAC,oBAAoB,CAAC,GAAW;QAC7C,IAAI,CAAC;YACJ,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;YAClC,OAAO,GAAG,YAAY,CAAC,QAAQ,GAAG,YAAY,CAAC,MAAM,EAAE,CAAC;QACzD,CAAC;QAAC,MAAM,CAAC,CAAA,CAAC;IACX,CAAC;IAED;;;;;OAKG;IACI,MAAM,CAAC,YAAY,CAAC,MAAc,EAAE,aAAqB;QAC/D,IAAI,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC;YACnD,OAAO,GAAG,YAAY,CAAC,mBAAmB,CAAC,MAAM,CAAC,IAAI,YAAY,CAAC,kBAAkB,CAAC,aAAa,CAAC,EAAE,CAAC;QACxG,CAAC;IACF,CAAC;IAED;;;;;;;OAOG;IACI,MAAM,CAAC,oBAAoB,CAAC,OAAe;QACjD,8EAA8E;QAC9E,2FAA2F;QAC3F,OAAO,OAAO,CAAC,OAAO,CAAC,wBAAwB,EAAE,EAAE,CAAC,EAAE,CAAC,kBAAkB,CAAC,EAAE,CAAC,CAAC,CAAC;IAChF,CAAC;IAED;;;;;OAKG;IACI,MAAM,CAAC,aAAa,CAAC,GAAW,EAAE,SAAkB;QAC1D,IAAI,CAAC,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,WAAW,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YACzF,OAAO,GAAG,CAAC;QACZ,CAAC;QAED,IAAI,CAAC;YACJ,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,qBAAqB,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YAClF,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,CAAC;YACxC,SAAS,CAAC,QAAQ,GAAG,YAAY,CAAC,QAAQ,CAAC;YAC3C,SAAS,CAAC,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC;YACnC,SAAS,CAAC,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC;YACnC,OAAO,SAAS,CAAC,QAAQ,EAAE,CAAC;QAC7B,CAAC;QAAC,MAAM,CAAC,CAAA,CAAC;QAEV,OAAO,GAAG,CAAC;IACZ,CAAC;CACD","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { Is, StringHelper } from \"@twin.org/core\";\n\n/**\n * Class to help with handling http URLs.\n */\nexport class HttpUrlHelper {\n\t/**\n\t * Extract the origin from the url which includes protocol,host,port.\n\t * @see https://developer.mozilla.org/en-US/docs/Web/API/URL/origin\n\t * @param url The url to extract the origin from.\n\t * @returns The extracted origin.\n\t */\n\tpublic static extractOrigin(url: string): string | undefined {\n\t\ttry {\n\t\t\tconst convertedUrl = new URL(url);\n\t\t\treturn convertedUrl.origin;\n\t\t} catch {}\n\t}\n\n\t/**\n\t * Extract the path from the url.\n\t * @see https://developer.mozilla.org/en-US/docs/Web/API/URL/pathname\n\t * @param url The url to extract the path from.\n\t * @returns The extracted path.\n\t */\n\tpublic static extractPath(url: string): string | undefined {\n\t\ttry {\n\t\t\tconst convertedUrl = new URL(url);\n\t\t\treturn convertedUrl.pathname;\n\t\t} catch {}\n\t}\n\n\t/**\n\t * Extract the search from the url.\n\t * @see https://developer.mozilla.org/en-US/docs/Web/API/URL/search\n\t * @param url The url to extract the search from.\n\t * @returns The extracted search.\n\t */\n\tpublic static extractSearch(url: string): string | undefined {\n\t\ttry {\n\t\t\tconst convertedUrl = new URL(url);\n\t\t\treturn convertedUrl.search;\n\t\t} catch {}\n\t}\n\n\t/**\n\t * Extract the path and search from the url.\n\t * @param url The url to extract the path and search from.\n\t * @returns The extracted path and search.\n\t */\n\tpublic static extractPathAndSearch(url: string): string | undefined {\n\t\ttry {\n\t\t\tconst convertedUrl = new URL(url);\n\t\t\treturn `${convertedUrl.pathname}${convertedUrl.search}`;\n\t\t} catch {}\n\t}\n\n\t/**\n\t * Combine the urls parts.\n\t * @param origin The origin to combine.\n\t * @param pathAndSearch The path and search to combine.\n\t * @returns The combined parts.\n\t */\n\tpublic static combineParts(origin: string, pathAndSearch: string): string | undefined {\n\t\tif (Is.string(origin) && Is.string(pathAndSearch)) {\n\t\t\treturn `${StringHelper.trimTrailingSlashes(origin)}/${StringHelper.trimLeadingSlashes(pathAndSearch)}`;\n\t\t}\n\t}\n\n\t/**\n\t * Encode a single URL path segment per RFC 3986 §3.3.\n\t * Unlike encodeURIComponent, sub-delimiters ($ & + , ; =) and the colon and\n\t * at-sign characters that are valid unencoded in path segments are preserved.\n\t * @see https://datatracker.ietf.org/doc/html/rfc3986#section-3.3\n\t * @param segment The raw path segment value to encode.\n\t * @returns The percent-encoded path segment.\n\t */\n\tpublic static encodeUriPathSegment(segment: string): string {\n\t\t// RFC 3986 §3.3: only encode characters outside the allowed path segment set.\n\t\t// Allowed: unreserved (A-Za-z0-9 - . _ ~), sub-delimiters (! $ & ' ( ) * + , ; =), and : @\n\t\treturn segment.replace(/[^\\w!$&'()*+,.:;=@~-]/g, ch => encodeURIComponent(ch));\n\t}\n\n\t/**\n\t * Replace the origin in the url.\n\t * @param url The url to replace the origin in.\n\t * @param newOrigin The new origin to use.\n\t * @returns The url with the replaced origin.\n\t */\n\tpublic static replaceOrigin(url: string, newOrigin?: string): string {\n\t\tif (!Is.stringValue(url) || !Is.stringValue(newOrigin) || !newOrigin.startsWith(\"http\")) {\n\t\t\treturn url;\n\t\t}\n\n\t\ttry {\n\t\t\tconst parsedUrl = new URL(url.startsWith(\"/\") ? `http://placeholder${url}` : url);\n\t\t\tconst newParsedUrl = new URL(newOrigin);\n\t\t\tparsedUrl.protocol = newParsedUrl.protocol;\n\t\t\tparsedUrl.host = newParsedUrl.host;\n\t\t\tparsedUrl.port = newParsedUrl.port;\n\t\t\treturn parsedUrl.toString();\n\t\t} catch {}\n\n\t\treturn url;\n\t}\n}\n"]}

package/dist/es/models/config/IBaseRestClientConfig.js.map

@@ -1 +1 @@
-{"version":3,"file":"IBaseRestClientConfig.js","sourceRoot":"","sources":["../../../../src/models/config/IBaseRestClientConfig.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IHttpHeaders } from \"@twin.org/web\";\n\n/**\n * Definition for the configuration of a rest client.\n */\nexport interface IBaseRestClientConfig {\n\t/**\n\t * The endpoint where the api is hosted.\n\t */\n\tendpoint: string;\n\n\t/**\n\t * The prefix to the routes.\n\t */\n\tpathPrefix?: string;\n\n\t/**\n\t * The headers to include in requests.\n\t */\n\theaders?: IHttpHeaders;\n\n\t/**\n\t * Timeout for requests in ms.\n\t */\n\ttimeout?: number;\n\n\t/**\n\t * Include credentials in the request, defaults to true.\n\t */\n\tincludeCredentials?: boolean;\n}\n"]}
+{"version":3,"file":"IBaseRestClientConfig.js","sourceRoot":"","sources":["../../../../src/models/config/IBaseRestClientConfig.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IError } from \"@twin.org/core\";\nimport type { IHttpHeaders } from \"@twin.org/web\";\n\n/**\n * Definition for the configuration of a rest client.\n */\nexport interface IBaseRestClientConfig {\n\t/**\n\t * The endpoint where the api is hosted.\n\t */\n\tendpoint: string;\n\n\t/**\n\t * The prefix to the routes.\n\t */\n\tpathPrefix?: string;\n\n\t/**\n\t * The headers to include in requests.\n\t */\n\theaders?: IHttpHeaders;\n\n\t/**\n\t * Timeout for requests in ms.\n\t */\n\ttimeout?: number;\n\n\t/**\n\t * Include credentials in the request, defaults to true.\n\t */\n\tincludeCredentials?: boolean;\n\n\t/**\n\t * Hook to provide headers asynchronously.\n\t * @returns A promise that resolves to the headers.\n\t */\n\tcustomHeaders?: () => Promise<IHttpHeaders>;\n\n\t/**\n\t * Hook to provide an authorization header value asynchronously.\n\t * @returns A promise that resolves to the authorization header value.\n\t */\n\tcustomAuthHeader?: () => Promise<string>;\n\n\t/**\n\t * Hook to handle authorization failures asynchronously.\n\t * @returns A promise that resolves when the auth failure handling is complete.\n\t */\n\tonAuthFailure?: (err: IError) => Promise<void>;\n}\n"]}

package/dist/es/models/services/IHostingComponent.js.map

@@ -1 +1 @@
-{"version":3,"file":"IHostingComponent.js","sourceRoot":"","sources":["../../../../src/models/services/IHostingComponent.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IComponent } from \"@twin.org/core\";\n\n/**\n * The information about the hosting of the API.\n */\nexport interface IHostingComponent extends IComponent {\n\t/**\n\t * Get the public origin for the hosting.\n\t * @param serverRequestUrl The url of the current server request if there is one.\n\t * @returns The public origin.\n\t */\n\tgetPublicOrigin(serverRequestUrl?: string): Promise<string>;\n\n\t/**\n\t * Get the public origin for the tenant if one exists.\n\t * @param tenantId The tenant identifier.\n\t * @returns The public origin for the tenant.\n\t */\n\tgetTenantOrigin(tenantId: string): Promise<string | undefined>;\n\n\t/**\n\t * Build a public url based on the public origin and the url provided.\n\t * @param url The url to build upon the public origin.\n\t * @returns The full url based on the public origin.\n\t */\n\tbuildPublicUrl(url: string): Promise<string>;\n}\n"]}
+{"version":3,"file":"IHostingComponent.js","sourceRoot":"","sources":["../../../../src/models/services/IHostingComponent.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IComponent } from \"@twin.org/core\";\nimport type { IHttpRequestQuery } from \"../protocol/IHttpRequestQuery.js\";\n\n/**\n * The information about the hosting of the API.\n */\nexport interface IHostingComponent extends IComponent {\n\t/**\n\t * Get the public origin for the hosting.\n\t * @param serverRequestUrl The url of the current server request if there is one.\n\t * @returns The public origin.\n\t */\n\tgetPublicOrigin(serverRequestUrl?: string): Promise<string>;\n\n\t/**\n\t * Get the public origin for the tenant if one exists.\n\t * @param tenantId The tenant identifier.\n\t * @returns The public origin for the tenant.\n\t */\n\tgetTenantOrigin(tenantId: string): Promise<string | undefined>;\n\n\t/**\n\t * Build a public url based on the public origin and the url provided.\n\t * @param url The url to build upon the public origin.\n\t * @returns The full url based on the public origin.\n\t */\n\tbuildPublicUrl(url: string): Promise<string>;\n\n\t/**\n\t * Add encrypted key/value pairs to a URL's query string.\n\t * Existing query parameters on the URL are preserved; the provided params are\n\t * merged in and then encrypted before being written back to the URL.\n\t * @param url The base URL to add parameters to.\n\t * @param params The key/value pairs to encrypt and append.\n\t * @returns The URL with the encrypted parameters added.\n\t */\n\taddEncryptedParamsToUrl(url: string, params: IHttpRequestQuery): Promise<string>;\n\n\t/**\n\t * Decrypt specified keys from a query parameter object and return their plain-text values.\n\t * @param queryParams The HTTP request query containing the encrypted parameters.\n\t * @param keys The keys to decrypt.\n\t * @returns A map of the decrypted key/value pairs that were present.\n\t */\n\tgetDecryptedParamsFromQueryParams(\n\t\tqueryParams: IHttpRequestQuery | undefined,\n\t\tkeys: string[]\n\t): Promise<IHttpRequestQuery>;\n\n\t/**\n\t * Encrypt the tenant id and append it as a query parameter to the given URL.\n\t * @param url The URL to append the encrypted tenant token to.\n\t * @param tenantId The tenant identifier to encrypt and add.\n\t * @returns The URL with the encrypted tenant token added as a query parameter.\n\t */\n\taddTenantTokenToUrl(url: string, tenantId: string): Promise<string>;\n\t/**\n\t * Get the tenant token from the query parameters.\n\t * @param queryParams The HTTP request query containing the parameters.\n\t * @returns The tenant token if it exists.\n\t */\n\tgetTenantTokenFromQueryParams(\n\t\tqueryParams: IHttpRequestQuery | undefined\n\t): Promise<string | undefined>;\n\n\t/**\n\t * Encrypt query parameters using the hosting component's encryption mechanism.\n\t * @param httpRequestQuery The HTTP request query containing the parameters to encrypt.\n\t * @param keys The keys of the parameters to encrypt.\n\t * @returns A promise that resolves when the query parameters have been encrypted.\n\t */\n\tencryptQueryParams(\n\t\thttpRequestQuery: IHttpRequestQuery | undefined,\n\t\tkeys: string[]\n\t): Promise<void>;\n\n\t/**\n\t * Decrypt query parameters using the hosting component's encryption mechanism.\n\t * @param httpRequestQuery The HTTP request query containing the encrypted values.\n\t * @param keys The keys of the parameters to decrypt.\n\t * @returns A promise that resolves when the query parameters have been decrypted.\n\t */\n\tdecryptQueryParams(\n\t\thttpRequestQuery: IHttpRequestQuery | undefined,\n\t\tkeys: string[]\n\t): Promise<void>;\n\n\t/**\n\t * Encrypt a parameter value using the hosting component's encryption mechanism.\n\t * @param paramValue The value of the parameter to encrypt.\n\t * @returns A promise that resolves to the encrypted value of the parameter.\n\t */\n\tencryptParam(paramValue: string): Promise<string>;\n\n\t/**\n\t * Decrypt a parameter value using the hosting component's encryption mechanism.\n\t * @param encryptedValue The encrypted value of the parameter.\n\t * @returns A promise that resolves to the decrypted value of the parameter.\n\t */\n\tdecryptParam(encryptedValue: string): Promise<string>;\n}\n"]}

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

@@ -36,6 +36,15 @@ export declare class HttpUrlHelper {
      * @returns The combined parts.
      */
     static combineParts(origin: string, pathAndSearch: string): string | undefined;
+    /**
+     * 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.
+     * @see https://datatracker.ietf.org/doc/html/rfc3986#section-3.3
+     * @param segment The raw path segment value to encode.
+     * @returns The percent-encoded path segment.
+     */
+    static encodeUriPathSegment(segment: string): string;
     /**
      * Replace the origin in the url.
      * @param url The url to replace the origin in.

package/dist/types/models/config/IBaseRestClientConfig.d.ts

@@ -1,3 +1,4 @@
+import type { IError } from "@twin.org/core";
 import type { IHttpHeaders } from "@twin.org/web";
 /**
  * Definition for the configuration of a rest client.
@@ -23,4 +24,19 @@ export interface IBaseRestClientConfig {
      * Include credentials in the request, defaults to true.
      */
     includeCredentials?: boolean;
+    /**
+     * Hook to provide headers asynchronously.
+     * @returns A promise that resolves to the headers.
+     */
+    customHeaders?: () => Promise<IHttpHeaders>;
+    /**
+     * Hook to provide an authorization header value asynchronously.
+     * @returns A promise that resolves to the authorization header value.
+     */
+    customAuthHeader?: () => Promise<string>;
+    /**
+     * Hook to handle authorization failures asynchronously.
+     * @returns A promise that resolves when the auth failure handling is complete.
+     */
+    onAuthFailure?: (err: IError) => Promise<void>;
 }

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

@@ -1,4 +1,5 @@
 import type { IComponent } from "@twin.org/core";
+import type { IHttpRequestQuery } from "../protocol/IHttpRequestQuery.js";
 /**
  * The information about the hosting of the API.
  */
@@ -21,4 +22,59 @@ export interface IHostingComponent extends IComponent {
      * @returns The full url based on the public origin.
      */
     buildPublicUrl(url: string): Promise<string>;
+    /**
+     * Add encrypted key/value pairs to a URL's query string.
+     * Existing query parameters on the URL are preserved; the provided params are
+     * merged in and then encrypted before being written back to the URL.
+     * @param url The base URL to add parameters to.
+     * @param params The key/value pairs to encrypt and append.
+     * @returns The URL with the encrypted parameters added.
+     */
+    addEncryptedParamsToUrl(url: string, params: IHttpRequestQuery): Promise<string>;
+    /**
+     * Decrypt specified keys from a query parameter object and return their plain-text values.
+     * @param queryParams The HTTP request query containing the encrypted parameters.
+     * @param keys The keys to decrypt.
+     * @returns A map of the decrypted key/value pairs that were present.
+     */
+    getDecryptedParamsFromQueryParams(queryParams: IHttpRequestQuery | undefined, keys: string[]): Promise<IHttpRequestQuery>;
+    /**
+     * Encrypt the tenant id and append it as a query parameter to the given URL.
+     * @param url The URL to append the encrypted tenant token to.
+     * @param tenantId The tenant identifier to encrypt and add.
+     * @returns The URL with the encrypted tenant token added as a query parameter.
+     */
+    addTenantTokenToUrl(url: string, tenantId: string): Promise<string>;
+    /**
+     * Get the tenant token from the query parameters.
+     * @param queryParams The HTTP request query containing the parameters.
+     * @returns The tenant token if it exists.
+     */
+    getTenantTokenFromQueryParams(queryParams: IHttpRequestQuery | undefined): Promise<string | undefined>;
+    /**
+     * Encrypt query parameters using the hosting component's encryption mechanism.
+     * @param httpRequestQuery The HTTP request query containing the parameters to encrypt.
+     * @param keys The keys of the parameters to encrypt.
+     * @returns A promise that resolves when the query parameters have been encrypted.
+     */
+    encryptQueryParams(httpRequestQuery: IHttpRequestQuery | undefined, keys: string[]): Promise<void>;
+    /**
+     * Decrypt query parameters using the hosting component's encryption mechanism.
+     * @param httpRequestQuery The HTTP request query containing the encrypted values.
+     * @param keys The keys of the parameters to decrypt.
+     * @returns A promise that resolves when the query parameters have been decrypted.
+     */
+    decryptQueryParams(httpRequestQuery: IHttpRequestQuery | undefined, keys: string[]): Promise<void>;
+    /**
+     * Encrypt a parameter value using the hosting component's encryption mechanism.
+     * @param paramValue The value of the parameter to encrypt.
+     * @returns A promise that resolves to the encrypted value of the parameter.
+     */
+    encryptParam(paramValue: string): Promise<string>;
+    /**
+     * Decrypt a parameter value using the hosting component's encryption mechanism.
+     * @param encryptedValue The encrypted value of the parameter.
+     * @returns A promise that resolves to the decrypted value of the parameter.
+     */
+    decryptParam(encryptedValue: string): Promise<string>;
 }

package/docs/changelog.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.0.3-next.29](https://github.com/twinfoundation/twin-api/compare/api-models-v0.0.3-next.28...api-models-v0.0.3-next.29) (2026-05-01)
+
+
+### Features
+
+* hosting service ([#109](https://github.com/twinfoundation/twin-api/issues/109)) ([985bf1f](https://github.com/twinfoundation/twin-api/commit/985bf1f5c07b09ecb800df7120bc2422ac7a6d25))
+
 ## [0.0.3-next.28](https://github.com/twinfoundation/twin-api/compare/api-models-v0.0.3-next.27...api-models-v0.0.3-next.28) (2026-04-30)
 
 

package/docs/examples.md

@@ -1,6 +1,6 @@
 # Models Examples
 
-These snippets show practical helpers for URL manipulation, request parameter conversion, and consistent error responses.
+These snippets show practical helpers for URL manipulation, request parameter conversion, consistent error responses, and secure parameter encryption.
 
 ## HttpUrlHelper
 
@@ -61,3 +61,140 @@ try {
   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/HttpUrlHelper.md

@@ -142,6 +142,34 @@ 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`

package/docs/reference/interfaces/IBaseRestClientConfig.md

@@ -41,3 +41,51 @@ Timeout for requests in ms.
 > `optional` **includeCredentials?**: `boolean`
 
 Include credentials in the request, defaults to true.
+
+***
+
+### customHeaders? {#customheaders}
+
+> `optional` **customHeaders?**: () => `Promise`\<`IHttpHeaders`\>
+
+Hook to provide headers asynchronously.
+
+#### Returns
+
+`Promise`\<`IHttpHeaders`\>
+
+A promise that resolves to the headers.
+
+***
+
+### customAuthHeader? {#customauthheader}
+
+> `optional` **customAuthHeader?**: () => `Promise`\<`string`\>
+
+Hook to provide an authorization header value asynchronously.
+
+#### Returns
+
+`Promise`\<`string`\>
+
+A promise that resolves to the authorization header value.
+
+***
+
+### onAuthFailure? {#onauthfailure}
+
+> `optional` **onAuthFailure?**: (`err`) => `Promise`\<`void`\>
+
+Hook to handle authorization failures asynchronously.
+
+#### Parameters
+
+##### err
+
+`IError`
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the auth failure handling is complete.

package/docs/reference/interfaces/IHostingComponent.md

@@ -71,3 +71,211 @@ The url to build upon the public origin.
 `Promise`\<`string`\>
 
 The full url based on the public origin.
+
+***
+
+### addEncryptedParamsToUrl() {#addencryptedparamstourl}
+
+> **addEncryptedParamsToUrl**(`url`, `params`): `Promise`\<`string`\>
+
+Add encrypted key/value pairs to a URL's query string.
+Existing query parameters on the URL are preserved; the provided params are
+merged in and then encrypted before being written back to the URL.
+
+#### Parameters
+
+##### url
+
+`string`
+
+The base URL to add parameters to.
+
+##### params
+
+[`IHttpRequestQuery`](IHttpRequestQuery.md)
+
+The key/value pairs to encrypt and append.
+
+#### Returns
+
+`Promise`\<`string`\>
+
+The URL with the encrypted parameters added.
+
+***
+
+### getDecryptedParamsFromQueryParams() {#getdecryptedparamsfromqueryparams}
+
+> **getDecryptedParamsFromQueryParams**(`queryParams`, `keys`): `Promise`\<[`IHttpRequestQuery`](IHttpRequestQuery.md)\>
+
+Decrypt specified keys from a query parameter object and return their plain-text values.
+
+#### Parameters
+
+##### queryParams
+
+[`IHttpRequestQuery`](IHttpRequestQuery.md) \| `undefined`
+
+The HTTP request query containing the encrypted parameters.
+
+##### keys
+
+`string`[]
+
+The keys to decrypt.
+
+#### Returns
+
+`Promise`\<[`IHttpRequestQuery`](IHttpRequestQuery.md)\>
+
+A map of the decrypted key/value pairs that were present.
+
+***
+
+### addTenantTokenToUrl() {#addtenanttokentourl}
+
+> **addTenantTokenToUrl**(`url`, `tenantId`): `Promise`\<`string`\>
+
+Encrypt the tenant id and append it as a query parameter to the given URL.
+
+#### Parameters
+
+##### url
+
+`string`
+
+The URL to append the encrypted tenant token to.
+
+##### tenantId
+
+`string`
+
+The tenant identifier to encrypt and add.
+
+#### Returns
+
+`Promise`\<`string`\>
+
+The URL with the encrypted tenant token added as a query parameter.
+
+***
+
+### getTenantTokenFromQueryParams() {#gettenanttokenfromqueryparams}
+
+> **getTenantTokenFromQueryParams**(`queryParams`): `Promise`\<`string` \| `undefined`\>
+
+Get the tenant token from the query parameters.
+
+#### Parameters
+
+##### queryParams
+
+[`IHttpRequestQuery`](IHttpRequestQuery.md) \| `undefined`
+
+The HTTP request query containing the parameters.
+
+#### Returns
+
+`Promise`\<`string` \| `undefined`\>
+
+The tenant token if it exists.
+
+***
+
+### encryptQueryParams() {#encryptqueryparams}
+
+> **encryptQueryParams**(`httpRequestQuery`, `keys`): `Promise`\<`void`\>
+
+Encrypt query parameters using the hosting component's encryption mechanism.
+
+#### Parameters
+
+##### httpRequestQuery
+
+[`IHttpRequestQuery`](IHttpRequestQuery.md) \| `undefined`
+
+The HTTP request query containing the parameters to encrypt.
+
+##### keys
+
+`string`[]
+
+The keys of the parameters to encrypt.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the query parameters have been encrypted.
+
+***
+
+### decryptQueryParams() {#decryptqueryparams}
+
+> **decryptQueryParams**(`httpRequestQuery`, `keys`): `Promise`\<`void`\>
+
+Decrypt query parameters using the hosting component's encryption mechanism.
+
+#### Parameters
+
+##### httpRequestQuery
+
+[`IHttpRequestQuery`](IHttpRequestQuery.md) \| `undefined`
+
+The HTTP request query containing the encrypted values.
+
+##### keys
+
+`string`[]
+
+The keys of the parameters to decrypt.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the query parameters have been decrypted.
+
+***
+
+### encryptParam() {#encryptparam}
+
+> **encryptParam**(`paramValue`): `Promise`\<`string`\>
+
+Encrypt a parameter value using the hosting component's encryption mechanism.
+
+#### Parameters
+
+##### paramValue
+
+`string`
+
+The value of the parameter to encrypt.
+
+#### Returns
+
+`Promise`\<`string`\>
+
+A promise that resolves to the encrypted value of the parameter.
+
+***
+
+### decryptParam() {#decryptparam}
+
+> **decryptParam**(`encryptedValue`): `Promise`\<`string`\>
+
+Decrypt a parameter value using the hosting component's encryption mechanism.
+
+#### Parameters
+
+##### encryptedValue
+
+`string`
+
+The encrypted value of the parameter.
+
+#### Returns
+
+`Promise`\<`string`\>
+
+A promise that resolves to the decrypted value of the parameter.

package/package.json

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