@twin.org/web 0.0.3-next.4 → 0.0.3-next.40

package/dist/types/utils/headerHelper.d.ts

@@ -1,7 +1,14 @@
+import type { HttpLinkRelType } from "../models/httpLinkRelType.js";
+import type { IHttpHeaders } from "../models/IHttpHeaders.js";
+import type { IHttpLinkHeader } from "../models/IHttpLinkHeader.js";
 /**
  * Class to helper with header operations.
  */
 export declare class HeaderHelper {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
     /**
      * Create a bearer token header.
      * @param token The token to create the header for.
@@ -14,4 +21,112 @@ export declare class HeaderHelper {
      * @returns The extracted token if it exists.
      */
     static extractBearer(header: unknown): string;
+    /**
+     * Extract parsed language preferences from the Accept-Language header.
+     * @param headers The HTTP request headers.
+     * @returns The parsed language preferences ordered by highest quality first, or undefined if missing or invalid.
+     */
+    static extractAcceptLanguage(headers?: IHttpHeaders): {
+        language: string;
+        quality: number;
+    }[] | undefined;
+    /**
+     * Parse one or more Accept-Language header values into language preferences.
+     * @param acceptLanguage The Accept-Language header value or values.
+     * @returns The parsed language preferences ordered by highest quality first, or undefined if missing or if any entry is invalid.
+     */
+    static parseAcceptLanguage(acceptLanguage: string | string[] | undefined): {
+        language: string;
+        quality: number;
+    }[] | undefined;
+    /**
+     * Extract client IP addresses from HTTP request headers.
+     * Checks all `X-Forwarded-For` and `X-Real-IP` header values for proxied requests.
+     * @param headers The HTTP request headers.
+     * @returns The extracted client IP addresses in header order.
+     */
+    static extractClientIps(headers?: IHttpHeaders): string[];
+    /**
+     * Extract the User-Agent header from the HTTP request context.
+     * @param headers The HTTP request headers.
+     * @param maxLength Optional maximum length for the User-Agent string to prevent excessively long values.
+     * @returns The user agent string or undefined if not available.
+     */
+    static extractUserAgent(headers?: IHttpHeaders, maxLength?: number): string | undefined;
+    /**
+     * Extract a correlation ID for request tracing from the X-Correlation-ID header.
+     * @param headers The HTTP request headers.
+     * @param maxLength Optional maximum length for the extracted correlation ID.
+     * @returns The correlation ID, or undefined if the header is missing or invalid.
+     */
+    static extractCorrelationId(headers?: IHttpHeaders, maxLength?: number): string | undefined;
+    /**
+     * Validate if a string is a valid IP address (IPv4 or IPv6).
+     * @param ip The IP address to validate.
+     * @returns True if valid, false otherwise.
+     */
+    static isIpAddress(ip: string): boolean;
+    /**
+     * Validate if a string is a valid IP address IPv4.
+     * @param ip The IP address to validate.
+     * @returns True if valid, false otherwise.
+     */
+    static isIpAddressV4(ip: string): boolean;
+    /**
+     * Validate if a string is a valid IP address IPv6.
+     * @param ip The IP address to validate.
+     * @returns True if valid, false otherwise.
+     */
+    static isIpAddressV6(ip: string): boolean;
+    /**
+     * Extract the first occurrence of properties from a Link header for a specific relation type.
+     * @param linkHeader The Link header value in format `<url>; rel="..."; param1=""; param2=""`.
+     * @param relation The relation type to extract.
+     * @returns The extracted URL, rel and optional params or undefined if invalid/missing.
+     * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Link
+     */
+    static extractLinkHeaderRelation(linkHeader: string | string[] | undefined, relation: HttpLinkRelType | string | RegExp): IHttpLinkHeader | undefined;
+    /**
+     * Extract multiple properties from a Link header for a specific relation type.
+     * @param linkHeader The Link header value in format `<url>; rel="..."; param1=""; param2=""`.
+     * @param relation The relation type to extract.
+     * @returns The extracted URL, rel and optional params or undefined if invalid/missing.
+     * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Link
+     */
+    static extractLinkHeaderRelations(linkHeader: string | string[] | undefined, relation: HttpLinkRelType | string | RegExp): IHttpLinkHeader[] | undefined;
+    /**
+     * Extract the link headers.
+     * @param linkHeader The Link header value in format `<url>; rel="..."; param1=""; param2=""`.
+     * @returns The extracted possible array of URL, rel and optional params or undefined if invalid/missing.
+     * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Link
+     */
+    static extractLinkHeaders(linkHeader: string | string[] | undefined): IHttpLinkHeader[] | undefined;
+    /**
+     * Split a combined Link header value into individual link-value segments, comma separated.
+     * @param linkHeader Raw Link header string.
+     * @returns Array of individual link-value segments.
+     * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Link
+     */
+    static extractLinkHeaderSegments(linkHeader: string): string[];
+    /**
+     * Extract the properties from a Link header.
+     * @param linkHeader The Link header value in format `<url>; rel="..."; param1=""; param2=""`.
+     * @returns The extracted URL, rel and optional params or undefined if invalid/missing.
+     * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Link
+     */
+    static extractLinkHeader(linkHeader: string): IHttpLinkHeader | undefined;
+    /**
+     * Create a compliant Link header.
+     * @param url The URL to include in the Link header.
+     * @param urlQueryParams Optional query parameters to include in the URL.
+     * @param rel The relation type (e.g., "next", "prev", "self").
+     * @returns The formatted Link header string.
+     * @throws GeneralError if the URL or rel are invalid.
+     * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Link
+     */
+    static createLinkHeader(url: string, urlQueryParams: {
+        [id: string]: string;
+    } | undefined, rel: HttpLinkRelType | HttpLinkRelType[] | string | string[], params?: {
+        [id: string]: string;
+    }): string;
 }