perimeterx-js-core 0.7.1 → 0.9.0

package/lib/types/additional_activity_handler/AdditionalActivityHandler.d.ts

@@ -0,0 +1,3 @@
+import { ConfigurationParams } from '../config';
+import { ReadonlyContext } from '../context';
+export type AdditionalActivityHandler<Req, Res> = (config: ConfigurationParams<Req, Res>, context: ReadonlyContext<Req, Res>, request: Req) => void | Promise<void>;

package/lib/types/config/ConfigurationParams.d.ts

@@ -0,0 +1,83 @@
+import { CustomParametersFunction } from '../custom_parameters';
+import { AdditionalActivityHandler } from '../additional_activity_handler';
+import { CustomPreflightHandler, CustomBlockResponseHeadersHandler } from '../cors';
+import { CredentialEndpointConfiguration, CredentialIntelligenceVersion, CustomLoginSuccessfulCallback, LoginSuccessfulReportingMethod } from '../products';
+import { LoggerSeverity } from '../logger';
+import { ModuleMode } from '../utils';
+import { GraphQLOperationType } from '../graphql';
+export type ConfigurationParams<Req, Res> = {
+    px_app_id: string;
+    px_auth_token: string;
+    px_cookie_secret: string;
+    px_s2s_timeout?: number;
+    px_backend_url?: string;
+    px_blocking_score?: number;
+    px_user_agent_max_length?: number;
+    px_risk_cookie_max_length?: number;
+    px_risk_cookie_min_iterations?: number;
+    px_risk_cookie_max_iterations?: number;
+    px_logger_severity?: 'debug' | 'error' | 'none' | LoggerSeverity;
+    px_ip_headers?: string[];
+    px_module_enabled?: boolean;
+    px_module_mode?: 'monitor' | 'active_blocking' | ModuleMode;
+    px_advanced_blocking_response_enabled?: boolean;
+    px_max_activity_batch_size?: number;
+    px_batch_activities_timeout_ms?: number;
+    px_bypass_monitor_header?: string;
+    px_csp_enabled?: boolean;
+    px_csp_no_updates_max_interval_minutes?: number;
+    px_csp_policy_refresh_interval_minutes?: number;
+    px_enforced_routes?: string[];
+    px_first_party_enabled?: boolean;
+    px_custom_first_party_prefix?: string;
+    px_custom_first_party_sensor_endpoint?: string;
+    px_custom_first_party_xhr_endpoint?: string;
+    px_custom_first_party_captcha_endpoint?: string;
+    px_backend_captcha_url?: string;
+    px_backend_client_url?: string;
+    px_backend_collector_url?: string;
+    px_login_credentials_extraction_enabled?: boolean;
+    px_login_credentials_extraction?: CredentialEndpointConfiguration<Req, Res>[];
+    px_compromised_credentials_header?: string;
+    px_send_raw_username_on_additional_s2s_activity?: boolean;
+    px_additional_s2s_activity_header_enabled?: boolean;
+    px_automatic_additional_s2s_activity_enabled?: boolean;
+    px_credentials_intelligence_version?: 'v2' | 'multistep_sso' | 'both' | CredentialIntelligenceVersion;
+    px_login_successful_reporting_method?: 'status' | 'body' | 'header' | 'custom' | LoginSuccessfulReportingMethod;
+    px_login_successful_body_regex?: string;
+    px_login_successful_header_name?: string;
+    px_login_successful_header_value?: string;
+    px_login_successful_status?: number[];
+    px_monitored_routes?: string[];
+    px_sensitive_headers?: string[];
+    px_sensitive_routes?: string[];
+    px_filter_by_extension?: string[];
+    px_filter_by_http_method?: string[];
+    px_filter_by_ip?: string[];
+    px_filter_by_route?: string[];
+    px_filter_by_user_agent?: string[];
+    px_css_ref?: string;
+    px_js_ref?: string;
+    px_custom_cookie_header?: string;
+    px_custom_logo?: string;
+    px_proxy_url?: string;
+    px_jwt_cookie_name?: string;
+    px_jwt_cookie_user_id_field_name?: string;
+    px_jwt_cookie_additional_field_names?: string[];
+    px_jwt_header_name?: string;
+    px_jwt_header_user_id_field_name?: string;
+    px_jwt_header_additional_field_names?: string[];
+    px_graphql_enabled?: boolean;
+    px_graphql_routes?: string[];
+    px_sensitive_graphql_operation_names?: string[];
+    px_sensitive_graphql_operation_types?: Array<'query' | 'mutation' | 'subscription' | GraphQLOperationType>;
+    px_cors_support_enabled?: boolean;
+    px_cors_preflight_request_filter_enabled?: boolean;
+    px_logger_auth_token?: string;
+    px_extract_ip?: () => {};
+    px_additional_activity_handler?: AdditionalActivityHandler<Req, Res>;
+    px_enrich_custom_parameters?: CustomParametersFunction<Req, Res>;
+    px_login_successful_custom_callback?: CustomLoginSuccessfulCallback<Res>;
+    px_cors_custom_preflight_handler?: CustomPreflightHandler<Req>;
+    px_cors_create_custom_block_response_headers?: CustomBlockResponseHeadersHandler<Req>;
+};

package/lib/types/config/IConfiguration.d.ts

@@ -0,0 +1,312 @@
+import { ModuleMode } from '../utils';
+import { ILogger, LoggerSeverity } from '../logger';
+import { CustomParametersFunction } from '../custom_parameters';
+import { AdditionalActivityHandler } from '../additional_activity_handler';
+import { ConfigurationParams } from './ConfigurationParams';
+import { CustomPreflightHandler, CustomBlockResponseHeadersHandler } from '../cors';
+import { CredentialEndpointConfiguration, CredentialIntelligenceVersion, CustomLoginSuccessfulCallback, LoginSuccessfulReportingMethod } from '../products';
+export interface IConfiguration<Req, Res, ParamsType extends ConfigurationParams<Req, Res> = ConfigurationParams<Req, Res>> {
+    /**
+     * The application ID.
+     */
+    readonly appId: string;
+    /**
+     * The cookie secret used to decrypt the risk cookie.
+     */
+    readonly cookieSecret: string;
+    /**
+     * The token used to authenticate with the Human/PerimeterX backend.
+     */
+    readonly authToken: string;
+    /**
+     * Whether the enforcer is enabled.
+     */
+    readonly moduleEnabled: boolean;
+    /**
+     * The timeout for risk API calls, in milliseconds.
+     */
+    readonly s2sTimeout: number;
+    /**
+     * An interface used to log enforcer debug and error messages.
+     */
+    readonly logger: ILogger;
+    /**
+     * The logger severity level of the logger.
+     */
+    readonly loggerSeverity: LoggerSeverity;
+    /**
+     * The default module mode of the enforcer.
+     */
+    readonly moduleMode: ModuleMode;
+    /**
+     * An array of header names to remove from all requests to Human/PerimeterX backends.
+     */
+    readonly sensitiveHeaders: string[];
+    /**
+     * An array of agents that should not go through the enforcer flow.
+     */
+    readonly filteredUserAgents: string[];
+    /**
+     * An array of regular expressions or prefixes of routes that should not go through the enforcer flow.
+     */
+    readonly filteredRoutes: string[];
+    /**
+     * An array of extensions that should not go through the enforcer flow.
+     */
+    readonly filteredExtensions: string[];
+    /**
+     * An array of IP addresses that should not go through the enforcer flow.
+     */
+    readonly filteredIps: string[];
+    /**
+     * An array of HTTP methods that should not go through the enforcer flow.
+     */
+    readonly filteredHttpMethods: string[];
+    /**
+     * An array of header names from which to extract the request IP.
+     */
+    readonly ipHeaders: string[];
+    /**
+     * An array of regular expressions or prefixes of routes that should go through the enforcer flow
+     * in active_blocking rather than monitor mode.
+     */
+    readonly enforcedRoutes: string[];
+    /**
+     * An array of regular expressions or prefixes of routes that should trigger a risk API call
+     * even if a valid, unexpired, low-score risk cookie is present.
+     */
+    readonly sensitiveRoutes: string[];
+    /**
+     * An array of regular expressions or prefixes of routes that should go through the enforcer flow
+     * in monitor rather than active_blocking mode.
+     */
+    readonly monitoredRoutes: string[];
+    /**
+     * The name of the header that contains the PX cookies.
+     */
+    readonly customCookieHeader: string;
+    /**
+     * Whether the enforcer should respond to first party endpoints.
+     */
+    readonly firstPartyEnabled: boolean;
+    /**
+     * The customized prefix to use for first party requests.
+     */
+    readonly customFirstPartyPrefix: string;
+    /**
+     * The customized endpoint to use for the sensor script. This will
+     * take precedence over if a custom first party prefix is configured.
+     */
+    readonly customFirstPartySensorEndpoint: string;
+    /**
+     * The customized endpoint to use for the XHR requests. This will
+     * take precedence over if a custom first party prefix is configured.
+     */
+    readonly customFirstPartyXhrEndpoint: string;
+    /**
+     * The customized endpoint to use for the captcha script. This will
+     * take precedence over if a custom first party prefix is configured.
+     */
+    readonly customFirstPartyCaptchaEndpoint: string;
+    /**
+     * Whether the enforcer should return a JSON block response in cases where the
+     * Accept header on the request includes application/json.
+     */
+    readonly advancedBlockingResponseEnabled: boolean;
+    /**
+     * The name of the header which, if present on the request with a value of 1, should
+     * trigger the request to go through the enforcer flow in active_blocking mode.
+     */
+    readonly bypassMonitorHeader: string;
+    /**
+     * The origin the enforcer will use to make risk API requests.
+     */
+    readonly backendScoreApiUrl: string;
+    /**
+     * The origin the enforcer will use to proxy captcha script requests.
+     */
+    readonly backendCaptchaUrl: string;
+    /**
+     * The origin the enforcer will use to proxy sensor script requests.
+     */
+    readonly backendClientUrl: string;
+    /**
+     * The origin the enforcer will use to send first-party XHR and async activities.
+     */
+    readonly backendCollectorUrl: string;
+    /**
+     * An alternative third-party URL to retrieve the captcha script for the block page in case of error.
+     */
+    readonly altBackendCaptchaUrl: string;
+    /**
+     * The name and version of the enforcer module.
+     */
+    readonly moduleVersion: string;
+    /**
+     * The risk score at and above which the request should be blocked.
+     */
+    readonly blockingScore: number;
+    /**
+     * A URL to a custom CSS file that should be added to the block page.
+     */
+    readonly cssRef: string;
+    /**
+     * A URL to a custom JS file that should be added to the block page.
+     */
+    readonly jsRef: string;
+    /**
+     * A URL to a custom logo that should be added to the block page.
+     */
+    readonly customLogo: string;
+    /**
+     * The maximum expected iterations for PBKDF2. Used for Cookie v3 only.
+     */
+    readonly riskCookieMaxIterations: number;
+    /**
+     * The minimum expected iterations for PBKDF2. Used for Cookie v3 only.
+     */
+    readonly riskCookieMinIterations: number;
+    /**
+     * The maximum expected length of risk cookie beyond which it will not be processed.
+     */
+    readonly riskCookieMaxLength: number;
+    /**
+     * The maximum expected length of the user-agent beyond which it will be truncated.
+     */
+    readonly userAgentMaxLength: number;
+    /**
+     * The batch size at which asynchronous activities are sent to the collector.
+     */
+    readonly maxActivityBatchSize: number;
+    /**
+     * The maximum amount of time to wait before sending asynchronous activities to the collector.
+     */
+    readonly activityBatchTimeoutMs: number;
+    /**
+     * Whether parsing of GraphQL request bodies should be enabled.
+     */
+    readonly graphqlEnabled: boolean;
+    /**
+     * Routes that should trigger GraphQL parsing by the enforcer.
+     */
+    readonly graphqlRoutes: string[];
+    /**
+     * An array of GraphQL operation names that should trigger a risk API call
+     * even if a valid, unexpired, low-score risk cookie is present.
+     */
+    readonly sensitiveGraphqlOperationNames: string[];
+    /**
+     * An array of GraphQL operation types (e.g., mutation) that should trigger a risk API call
+     * even if a valid, unexpired, low-score risk cookie is present.
+     */
+    readonly sensitiveGraphqlOperationTypes: string[];
+    /**
+     * A function returning CustomParameters that will be added to the enforcer activities.
+     */
+    readonly enrichCustomParameters: CustomParametersFunction<Req, Res>;
+    /**
+     * A function that will be called after the asynchronous activities are sent to the backend.
+     */
+    readonly additionalActivityHandler: AdditionalActivityHandler<Req, Res>;
+    /**
+     * Whether cors support feature should be enabled.
+     */
+    readonly corsSupportEnabled: boolean;
+    /**
+     * Function that will be called for preflight requests and returns response that will be returned to the client.
+     */
+    readonly corsCustomPreflightHandler: CustomPreflightHandler<Req>;
+    /**
+     * Function that returns an object with custom headers to be added to the block response.
+     */
+    readonly corsCreateCustomBlockResponseHeaders: CustomBlockResponseHeadersHandler<Req>;
+    /**
+     * Whether preflight requests will be filtered out from the enforcer.
+     */
+    readonly corsPreflightRequestFilterEnabled: boolean;
+    /**
+     * The name of cookie that contains the JWT token.
+     */
+    readonly jwtCookieName: string;
+    /**
+     * The name of the field/field path that contains the user ID.
+     */
+    readonly jwtCookieUserIdFieldName: string;
+    /**
+     * List of additional fields/fields' paths to be extracted from the JWT.
+     */
+    readonly jwtCookieAdditionalFieldNames: string[];
+    /**
+     * The name of the header that contains the JWT token.
+     */
+    readonly jwtHeaderName: string;
+    /**
+     * The name of the field/field path that contains the user ID.
+     */
+    readonly jwtHeaderUserIdFieldName: string;
+    /**
+     * List of additional fields/fields' paths to be extracted from the JWT.
+     */
+    readonly jwtHeaderAdditionalFieldNames: string[];
+    /**
+     * Whether to enable Credential Intelligence.
+     */
+    readonly ciEnabled: boolean;
+    /**
+     * An array of configuration objects for each credential endpoint.
+     */
+    readonly ciEndpoints: CredentialEndpointConfiguration<Req, Res>[];
+    /**
+     * The header name to be set on the incoming request if the credentials are compromised.
+     */
+    readonly ciCompromisedCredentialsHeaderName: string;
+    /**
+     * Whether to send the raw username on the additional_s2s activity.
+     */
+    readonly ciSendRawUsernameOnAdditionalS2SActivity: boolean;
+    /**
+     * Whether to send the additional_s2s activity automatically in the postEnforce function.
+     */
+    readonly ciAutomaticAdditionalS2SEnabled: boolean;
+    /**
+     * Whether to attach the additional_s2s payload and URL as headers to the original request.
+     * This should only be enabled if the additional_s2s activity is not sent automatically.
+     */
+    readonly ciAdditionalS2SHeaderEnabled: boolean;
+    /**
+     * The default Credential Intelligence version to use if none is defined for an endpoint.
+     */
+    readonly ciDefaultVersion: CredentialIntelligenceVersion;
+    /**
+     * The default login successful reporting method to use if none is defined for an endpoint.
+     */
+    readonly ciDefaultLoginSuccessfulReportingMethod: LoginSuccessfulReportingMethod;
+    /**
+     * The default login successful statuses to use if none is defined for an endpoint.
+     */
+    readonly ciDefaultLoginSuccessfulStatus: number[];
+    /**
+     * The default login successful body regex to use if none is defined for an endpoint.
+     */
+    readonly ciDefaultLoginSuccessfulBodyRegex: string;
+    /**
+     * The default login successful header name to use if none is defined for an endpoint.
+     */
+    readonly ciDefaultLoginSuccessfulHeaderName: string;
+    /**
+     * The default login successful header value to use if none is defined for an endpoint.
+     */
+    readonly ciDefaultLoginSuccessfulHeaderValue: string;
+    /**
+     * The default login successful custom callback to use if none is defined for an endpoint.
+     */
+    readonly ciDefaultLoginSuccessfulCustomCallback: CustomLoginSuccessfulCallback<Res>;
+    /**
+     * The authentication token for the logging service.
+     */
+    readonly loggerAuthToken: string;
+    /**
+     * Returns an object representation of the current configuration.
+     */
+    toParams(): ParamsType;
+}

package/lib/types/config/StaticConfigurationBase.d.ts

@@ -0,0 +1,92 @@
+import { IConfiguration } from './IConfiguration';
+import { ConfigurationParams } from './ConfigurationParams';
+import { CustomParametersFunction } from '../custom_parameters';
+import { AdditionalActivityHandler } from '../additional_activity_handler';
+import { ILogger, LoggerSeverity } from '../logger';
+import { CustomBlockResponseHeadersHandler, CustomPreflightHandler } from '../cors';
+import { ModuleMode } from '../utils';
+import { CredentialEndpointConfiguration, CredentialIntelligenceVersion, CustomLoginSuccessfulCallback, LoginSuccessfulReportingMethod } from '../products';
+export declare abstract class StaticConfigurationBase<Req, Res, ParamsType extends ConfigurationParams<Req, Res> = ConfigurationParams<Req, Res>> implements IConfiguration<Req, Res, ParamsType> {
+    protected readonly configParams: ParamsType;
+    protected internalLogger: ILogger;
+    protected abstract getModuleVersion(): string;
+    protected constructor(params: ParamsType, defaultParams?: Partial<ParamsType>);
+    private initialize;
+    private throwIfMissingRequiredField;
+    private getValidConfigValue;
+    private isValidConfigValue;
+    private getDefaultConfigurationValue;
+    toParams(): ParamsType;
+    get moduleVersion(): string;
+    get logger(): ILogger;
+    get appId(): string;
+    get authToken(): string;
+    get blockingScore(): number;
+    get bypassMonitorHeader(): string;
+    get cookieSecret(): string;
+    get customCookieHeader(): string;
+    get customLogo(): string;
+    get enforcedRoutes(): string[];
+    get filteredExtensions(): string[];
+    get filteredHttpMethods(): string[];
+    get filteredIps(): string[];
+    get filteredRoutes(): string[];
+    get filteredUserAgents(): string[];
+    get firstPartyEnabled(): boolean;
+    get customFirstPartyPrefix(): string;
+    get customFirstPartySensorEndpoint(): string;
+    get customFirstPartyXhrEndpoint(): string;
+    get customFirstPartyCaptchaEndpoint(): string;
+    get loggerSeverity(): LoggerSeverity;
+    get moduleEnabled(): boolean;
+    get moduleMode(): ModuleMode;
+    get monitoredRoutes(): string[];
+    get s2sTimeout(): number;
+    get sensitiveHeaders(): string[];
+    get sensitiveRoutes(): string[];
+    get advancedBlockingResponseEnabled(): boolean;
+    get backendScoreApiUrl(): string;
+    get ipHeaders(): string[];
+    get backendCaptchaUrl(): string;
+    get backendClientUrl(): string;
+    get backendCollectorUrl(): string;
+    get cssRef(): string;
+    get jsRef(): string;
+    get riskCookieMaxIterations(): number;
+    get riskCookieMinIterations(): number;
+    get riskCookieMaxLength(): number;
+    get userAgentMaxLength(): number;
+    get maxActivityBatchSize(): number;
+    get activityBatchTimeoutMs(): number;
+    get graphqlEnabled(): boolean;
+    get graphqlRoutes(): string[];
+    get sensitiveGraphqlOperationNames(): string[];
+    get sensitiveGraphqlOperationTypes(): string[];
+    get enrichCustomParameters(): CustomParametersFunction<Req, Res>;
+    get additionalActivityHandler(): AdditionalActivityHandler<Req, Res>;
+    get altBackendCaptchaUrl(): string;
+    get corsSupportEnabled(): boolean;
+    get corsCustomPreflightHandler(): CustomPreflightHandler<Req>;
+    get corsPreflightRequestFilterEnabled(): boolean;
+    get corsCreateCustomBlockResponseHeaders(): CustomBlockResponseHeadersHandler<Req>;
+    get jwtCookieAdditionalFieldNames(): string[];
+    get jwtCookieName(): string;
+    get jwtCookieUserIdFieldName(): string;
+    get jwtHeaderAdditionalFieldNames(): string[];
+    get jwtHeaderName(): string;
+    get jwtHeaderUserIdFieldName(): string;
+    get ciEnabled(): boolean;
+    get loggerAuthToken(): string;
+    get ciEndpoints(): CredentialEndpointConfiguration<Req, Res>[];
+    get ciCompromisedCredentialsHeaderName(): string;
+    get ciSendRawUsernameOnAdditionalS2SActivity(): boolean;
+    get ciAutomaticAdditionalS2SEnabled(): boolean;
+    get ciAdditionalS2SHeaderEnabled(): boolean;
+    get ciDefaultVersion(): CredentialIntelligenceVersion;
+    get ciDefaultLoginSuccessfulReportingMethod(): LoginSuccessfulReportingMethod;
+    get ciDefaultLoginSuccessfulStatus(): number[];
+    get ciDefaultLoginSuccessfulBodyRegex(): string;
+    get ciDefaultLoginSuccessfulHeaderName(): string;
+    get ciDefaultLoginSuccessfulHeaderValue(): string;
+    get ciDefaultLoginSuccessfulCustomCallback(): CustomLoginSuccessfulCallback<Res>;
+}

package/lib/types/context/DefaultContext.d.ts

@@ -0,0 +1,49 @@
+import { IConfiguration } from '../config';
+import { BlockAction } from '../blocker';
+import { CustomParameters } from '../custom_parameters';
+import { PXDE } from '../pxde';
+import { PXHD } from '../pxhd';
+import { TokenOrigin } from '../risk_token';
+import { IIncomingRequest, IOutgoingResponse, ReadonlyHeaders } from '../http';
+import { ICookieParser, IRequestIdGenerator, VidSource } from '../utils';
+import { IContext, RequestData, RiskApiData, ServerData, TlsData, TokenData } from './interfaces';
+import { ProductData, ProductName } from '../products';
+import { Action } from '../action';
+import { IURLParser } from '../utils';
+export type DefaultContextOptions = {
+    cookieParser?: ICookieParser;
+    requestIdGenerator: IRequestIdGenerator;
+    urlParser?: IURLParser;
+};
+export declare class DefaultContext<Req, Res> implements IContext<Req, Res> {
+    readonly requestId: string;
+    readonly tokenOrigin: TokenOrigin;
+    readonly requestData: RequestData<Req>;
+    readonly tokenData: TokenData<Req, Res>;
+    readonly riskApiData: RiskApiData;
+    readonly tlsData: TlsData;
+    readonly serverData: ServerData;
+    readonly productData: ProductData;
+    uuid: string;
+    vid?: string;
+    vidSource?: VidSource;
+    action: Action;
+    reasons?: Partial<Record<ProductName, string>>;
+    score?: number;
+    blockAction?: BlockAction;
+    pxhd?: PXHD;
+    pxde?: PXDE;
+    pxdeVerified?: boolean;
+    customParameters?: CustomParameters;
+    response?: IOutgoingResponse<Res>;
+    protected readonly config: IConfiguration<Req, Res>;
+    protected readonly urlParser: IURLParser;
+    constructor(config: IConfiguration<Req, Res>, request: IIncomingRequest<Req>, options: DefaultContextOptions);
+    get isMobile(): boolean;
+    protected createRequestData(config: IConfiguration<Req, Res>, request: IIncomingRequest<Req>, cookieParser?: ICookieParser): RequestData<Req>;
+    protected static getCookies(cookieParser: ICookieParser, ...cookieHeaderValues: string[]): Record<string, string>;
+    protected extractUserAgentFromHeader(config: IConfiguration<Req, Res>, headers: ReadonlyHeaders): string;
+    protected extractIpFromHeader(config: IConfiguration<Req, Res>, headers: ReadonlyHeaders): string;
+    protected getTokenOrigin(request: IIncomingRequest<Req>): TokenOrigin;
+    protected setCookiesOnContext(): void;
+}

package/lib/types/context/interfaces/RiskApiData.d.ts

@@ -0,0 +1,31 @@
+import { IRiskResponse, S2SErrorReason, RiskApiCallResult } from '../../risk_api';
+export type RiskApiData = {
+    /**
+     * The result of the risk API call.
+     */
+    riskApiCallResult: RiskApiCallResult;
+    /**
+     * The reason for the Risk API call.
+     */
+    s2sCallReason?: string;
+    /**
+     * An interface representing the risk API response.
+     */
+    riskResponse?: IRiskResponse;
+    /**
+     * The risk API round trip time in milliseconds.
+     */
+    riskRtt?: number;
+    /**
+     * The reason for the error during the risk API call if an error occurred.
+     */
+    errorReason?: S2SErrorReason;
+    /**
+     * The HTTP response status that was received for the risk API call if an error occurred.
+     */
+    errorHttpStatus?: number;
+    /**
+     * An error message that contains more details about the risk API error if an error occurred.
+     */
+    errorMessage?: string;
+};

package/lib/types/http/index.d.ts

@@ -0,0 +1,2 @@
+export * from './utils';
+export * from './interfaces';

package/lib/types/http/interfaces/IBody.d.ts

@@ -0,0 +1,25 @@
+import { AsyncOrSync } from 'ts-essentials';
+import { IFormData } from './IFormData';
+import { IURLSearchParams } from './IURLSearchParams';
+export interface IBody {
+    /**
+     * the unread body.
+     */
+    readonly body: any;
+    /**
+     * Converts the body to json (application/json)
+     */
+    json(): AsyncOrSync<any>;
+    /**
+     * Converts the body to formData (multipart/form-data)
+     */
+    formData(): AsyncOrSync<IFormData>;
+    /**
+     * Converts the body to text (plain/text, text/html, etc.)
+     */
+    text(): AsyncOrSync<string>;
+    /**
+     * Converts the body to a URL search params-like object (application/x-www-form-urlencoded)
+     */
+    formUrlEncoded(): AsyncOrSync<IURLSearchParams>;
+}

package/lib/types/http/interfaces/IIncomingRequest.d.ts

@@ -0,0 +1,32 @@
+import { HttpMethod } from '../utils';
+import { IBody } from './IBody';
+import { IHeaders } from './IHeaders';
+/**
+ * Describes a request that comes from the end user.
+ */
+export interface IIncomingRequest<Req> extends IBody {
+    /**
+     * Returns a url.
+     */
+    url: string;
+    /**
+     * Returns the method.
+     */
+    readonly method: HttpMethod;
+    /**
+     * Returns the request headers (for read usage).
+     */
+    readonly headers: IHeaders;
+    /**
+     * Return the client IP provided by the environment or null.
+     */
+    readonly clientIP: string | null;
+    /**
+     * Http version provided by the environment if supported.
+     */
+    readonly httpVersion?: string;
+    /**
+     * Returns the platform-specific request implementation of the request.
+     */
+    getUnderlyingRequest(): Req;
+}

package/lib/types/http/interfaces/IURL.d.ts

@@ -0,0 +1,9 @@
+import { IURLSearchParams } from './IURLSearchParams';
+export interface IURL {
+    href: string;
+    search: string;
+    origin: string;
+    host: string;
+    pathname: string;
+    searchParams: IURLSearchParams;
+}

package/lib/types/http/interfaces/IURLSearchParams.d.ts

@@ -0,0 +1,9 @@
+export interface IURLSearchParams {
+    get(name: string): string;
+    getAll(name: string): string[];
+    set(name: string, value: string): void;
+    append(name: string, value: string): void;
+    delete(name: string): void;
+    has(name: string): boolean;
+    forEach(callback: (value: string, key: string, params?: IURLSearchParams, thisArg?: any) => void): void;
+}

package/lib/types/http/interfaces/index.d.ts

@@ -0,0 +1,12 @@
+export * from './IHttpClient';
+export * from './IIncomingResponse';
+export * from './IIncomingRequest';
+export * from './IMinimalResponse';
+export * from './IOutgoingRequest';
+export * from './IOutgoingResponse';
+export * from './IBody';
+export * from './IHeaders';
+export * from './IFormData';
+export * from './ReadonlyHeaders';
+export * from './IURL';
+export * from './IURLSearchParams';