@sap-cloud-sdk/http-client/dist/http-client-types.d.ts

SAP Cloud SDK for JavaScript http-client

import type * as http from 'http';
import type { MiddlewareContext, Middleware, MiddlewareOptions } from '@sap-cloud-sdk/resilience';
import type { BasicProxyConfiguration } from '@sap-cloud-sdk/connectivity';
/**
 * Context for HttpRequests of the middleware.
 */
export interface HttpMiddlewareContext extends MiddlewareContext<HttpRequestConfig> {
    /**
     * JWT used in the request.
     */
    readonly jwt?: string;
    /**
     * Destination name used in the request.
     */
    readonly destinationName?: string;
}
/**
 * Options for http middleware.
 */
export type HttpMiddlewareOptions = MiddlewareOptions<HttpRequestConfig, HttpResponse, HttpMiddlewareContext>;
/**
 * Middleware for http requests.
 */
export type HttpMiddleware = Middleware<HttpRequestConfig, HttpResponse, HttpMiddlewareContext>;
/**
 * Represents the request configuration, that was inferred from a destination.
 */
export interface DestinationHttpRequestConfig {
    /**
     * Will be prepended to {@link HttpRequestConfigBase#url} unless `url` is absolute.
     */
    baseURL: string;
    /**
     * Additional headers to be sent.
     */
    headers: Record<string, string>;
    /**
     * URL parameters to be sent with the request.
     */
    params?: Record<string, string>;
    /**
     * Agent to be used when performing HTTP requests.
     */
    httpAgent?: http.Agent;
    /**
     * Agent to be used when performing HTTPS requests.
     */
    httpsAgent?: http.Agent;
    /**
     * Proxy configuration, when going through a proxy like the SAP Cloud Connector.
     */
    proxy?: BasicProxyConfiguration | false;
}
/**
 * HTTP Methods supported by the http-client.
 */
export type Method = 'get' | 'GET' | 'delete' | 'DELETE' | 'head' | 'HEAD' | 'options' | 'OPTIONS' | 'post' | 'POST' | 'put' | 'PUT' | 'patch' | 'PATCH';
/**
 * This interface is compatible with RawAxiosRequestConfig.
 */
export type HttpRequestConfig = HttpRequestConfigBase & {
    params?: Record<string, any>;
    headers?: Record<string, any>;
};
/**
 * This interface is similar to {@link HttpRequestConfig}. In addition, the `headers` and `params` can be defined with "origin" information.
 * @see {@link OriginOptions}
 */
export type HttpRequestConfigWithOrigin = HttpRequestConfigBase & {
    params?: OriginOptions;
    headers?: OriginOptions;
};
/**
 * Type of the parameter encoder.
 */
export type ParameterEncoder = (parameter: Record<string, any>) => Record<string, any>;
/**
 * Represents an HTTP request config. This is the basis for actual request configurations and request configurations with origins.
 */
export interface HttpRequestConfigBase {
    [key: string]: any;
    /**
     * Server URL that will be used for the request.
     * Relative `url` can be used together with {@link DestinationHttpRequestConfig#baseURL}.
     */
    url?: string;
    /**
     * The request method used when making the request.
     */
    method: Method;
    /**
     * Data sent in the request body.
     */
    data?: any;
    /**
     * Middleware {@link @sap-cloud-sdk/resilience!Middleware} to be applied to the request.
     * The request context is set using {@link @sap-cloud-sdk/http-client!HttpMiddlewareContext}.
     */
    middleware?: HttpMiddleware[];
    /**
     * The max size of the http response content in bytes.
     */
    maxContentLength?: number;
    /**
     * Set this to `false` to disable the proxy.
     * To configure the proxy you can add a {@link @sap-cloud-sdk/connectivity!ProxyConfiguration} to your destination.
     */
    proxy?: false;
    /**
     * The custom agent used when performing http requests.
     */
    httpAgent?: any;
    /**
     * The custom agent used when performing https requests.
     */
    httpsAgent?: any;
    /**
     * Encoder for the query parameters key and values. Per default parameters and keys are percent encoded.
     */
    parameterEncoder?: ParameterEncoder;
}
/**
 * @internal
 */
export type HttpRequest = DestinationHttpRequestConfig & HttpRequestConfig;
/**
 * @internal
 */
export type ExecuteHttpRequestFn<ReturnT> = (request: HttpRequest) => Promise<ReturnT>;
interface KnownHttpResponseFields {
    data: any;
    status: number;
    headers: any;
    request: any;
}
/**
 * Represents an HTTP response, that contains response code, headers, payload and the original request.
 * This interface is compatible with AxiosResponse.
 */
export interface HttpResponse extends KnownHttpResponseFields {
    [otherKey: string]: any;
}
/**
 * Options to configure the behavior when sending HTTP requests.
 * For example, whether the CSRF token is fetched automatically.
 */
export interface HttpRequestOptions {
    /**
     * A boolean value that indicates whether to fetch the csrf token for a non-get request.
     * For a get request, the csrf token is not fetched and this option is ignored.
     * By default, the value is `true`.
     */
    fetchCsrfToken?: boolean;
}
/**
 * The type for parameter in Custom Request Configuration.
 */
export type CustomRequestConfig = Pick<HttpRequestConfig, 'middleware' | 'maxContentLength' | 'proxy' | 'httpAgent' | 'httpsAgent' | 'parameterEncoder'> & Record<string, any>;
/**
 * This interface is used for defining e.g., headers and query parameters with origin information.
 * Options defined in `custom` take precedence over `requestConfig`.
 */
export interface OriginOptions {
    /**
     * Header or parameter properties originating from the request config.
     */
    requestConfig?: Record<string, any>;
    /**
     * Header or parameters properties set explicitly, which take precedence over `requestConfig`.
     */
    custom?: Record<string, any>;
}
/**
 * Type guard to check whether an object is of type `OriginOptions`.
 * Warn: there can be an edge case that one can define a normal header like the example:
 * {
 *   custom: {
 *     key: 'value'
 *   }
 * }
 * However, this will be treated as `OriginOptions`, as it contains `custom` as a key and an object as the value of the key.
 * This known issue can be handled by switching from `executeHttpClient` to `executeHttpClientWithOrigin`.
 * @param obj - Object to check.
 * @returns `true` if the object is a `OriginOptions` object, `false` otherwise.
 * @internal
 */
export declare function isOriginOptions(obj: any): obj is OriginOptions;
/**
 * @internal
 */
export declare function isHttpRequestConfigWithOrigin(requestConfig: HttpRequestConfig | HttpRequestConfigWithOrigin): requestConfig is HttpRequestConfigWithOrigin;
/**
 * @internal
 */
export interface OriginOptionsInternal {
    /**
     * @internal
     */
    requestConfig?: Record<string, any>;
    /**
     * @internal
     */
    destination?: Record<string, any>;
    /**
     * @internal
     */
    destinationProperty?: Record<string, any>;
    /**
     * @internal
     */
    custom?: Record<string, any>;
}
export {};