@trimble-oss/trimble-id/dist/types/HttpClient.d.ts

Trimble Identity SDK for JavaScript/TypeScript

/**
 * Copyright (c) Trimble Inc.
 */
type CommonRequestHeadersList = 'Accept' | 'Content-Length' | 'User-Agent' | 'Content-Encoding' | 'Authorization';
type ContentType = 'text/html' | 'text/plain' | 'multipart/form-data' | 'application/json' | 'application/x-www-form-urlencoded' | 'application/octet-stream';
type HeaderValue = string | string[] | number | boolean | null;
export type RequestHeaders = {
    [Key in CommonRequestHeadersList]?: HeaderValue;
} & {
    'Content-Type'?: ContentType;
} & {
    [key: string]: HeaderValue;
};
/**
 * Represents the response headers.
 */
export type ResponseHeaders = RequestHeaders;
/**
 * Represents a custom HTTP response with typed data and metadata.
 */
export interface Response<T = any> {
    /**
     * The response data
     */
    data: T;
    /**
     * The HTTP status code
     */
    status: number;
    /**
     * The HTTP status text
     */
    statusText: string;
    /**
     * The response headers
     */
    headers: ResponseHeaders;
}
/**
 * Represents the configuration options for an HTTP request.
 */
export interface RequestSettings {
    /**
     * `headers` are custom headers to be sent
     */
    headers?: RequestHeaders;
}
/**
 * Represents the default configuration options for an HTTP request.
 */
export interface DefaultSettings {
    /**
     * `headers` are custom headers to be sent
     */
    headers?: RequestHeaders;
    /**
     *`timeout` specifies the number of milliseconds before the request times out.
     * If the request takes longer than `timeout`, the request will be aborted.
     */
    timeout?: number;
}
/**
 * Represents an HTTP client.
 */
export default class HttpClient {
    private readonly _baseAddress;
    private readonly _defaultSettings;
    /**
     * Creates a new HttpClient instance with base address and optional default settings
     * @param {string} baseAddress The base address of the HTTP client
     * @param {DefaultSettings} defaultSettings The default settings for the HTTP client (optional)
     */
    constructor(baseAddress: string, defaultSettings?: DefaultSettings);
    /**
     * Creates a new HttpClient instance with default settings only (no base address)
     * @param {DefaultSettings} defaultSettings The default settings for the HTTP client
     */
    constructor(defaultSettings: DefaultSettings);
    /**
     * Creates a new HttpClient instance with no parameters (empty constructor)
     */
    constructor();
    /**
     * Sends a generic HTTP POST request to the specified relative address.
     * This method sends data without automatically setting JSON content type headers.
     * Use this for sending form data, binary data, or when you need to manually control content type.
     *
     * @param {string} relativeAddress The relative address to send the request to
     * @param {any} value The data to send with the request (optional)
     * @param {RequestSettings} requestSettings The additional settings for the request (optional)
     * @returns {Promise<T>} A promise that resolves with the response data if the request is successful
     */
    httpPost<T = any>(relativeAddress: string, value?: any, requestSettings?: RequestSettings): Promise<T>;
    /**
     * Sends a generic HTTP GET request to the specified relative address.
     * This method retrieves data without automatically setting JSON Accept headers.
     *
     * @param {string} relativeAddress The relative address of the resource
     * @param {RequestSettings} requestSettings The settings for the request
     * @returns {Promise<T>} A promise that resolves with the response data
     */
    httpGet<T = any>(relativeAddress: string, requestSettings?: RequestSettings): Promise<T>;
    /**
     * Sends a generic HTTP PUT request to the specified relative address.
     * This method sends data without automatically setting JSON content type headers.
     *
     * @param {string} relativeAddress The relative address to send the request to
     * @param {any} value The value to be sent in the request body
     * @param {RequestSettings} requestSettings Additional settings for the request
     * @returns {Promise<T>} A promise that resolves with the response data if the request is successful
     */
    httpPut<T = any>(relativeAddress: string, value?: any, requestSettings?: RequestSettings): Promise<T>;
    /**
     * Sends a generic HTTP PATCH request to the specified relative address.
     * This method sends data without automatically setting JSON content type headers.
     *
     * @param {string} relativeAddress The relative address to send the request to
     * @param {any} value The value to be sent in the request body
     * @param {RequestSettings} requestSettings Additional settings for the request
     * @returns {Promise<T>} A promise that resolves with the response data if the request is successful
     */
    httpPatch<T = any>(relativeAddress: string, value?: any, requestSettings?: RequestSettings): Promise<T>;
    /**
     * Sends a generic HTTP DELETE request to the specified relative address.
     * This method sends data without automatically setting JSON content type headers.
     *
     * @param {string} relativeAddress The relative address to send the request to
     * @param {any} content The content to include in the request body
     * @param {RequestSettings} requestSettings Additional settings for the request
     * @returns {Promise<T>} A promise that resolves with the response data if the request is successful
     */
    httpDelete<T = any>(relativeAddress: string, content?: any, requestSettings?: RequestSettings): Promise<T>;
    /**
     * Sends an HTTP POST request specifically formatted for JSON data.
     * This method automatically sets the 'Content-Type' and 'Accept' headers to 'application/json'.
     * Use this when sending JSON objects or when the server expects JSON content type.
     *
     * @param {string} relativeUrl The relative URL to send the request to
     * @param {any} value The JSON data to send in the request body
     * @param {RequestSettings} requestSettings Additional settings for the request (optional)
     * @returns {Promise<T>} A promise that resolves with the response JSON or rejects with an error
     */
    httpPostJSON<T = any>(relativeUrl: string, value: any, requestSettings?: RequestSettings): Promise<T>;
    /**
     * Sends an HTTP GET request specifically formatted for JSON data.
     * This method automatically sets the 'Accept' header to 'application/json'.
     * Use this when retrieving JSON objects or when the server returns JSON content type.
     *
     * @param {string} relativeUrl The relative URL to send the GET request to.
     * @param {RequestSettings} requestSettings The settings for the request
     * @returns {Promise<T>} A promise that resolves with the parsed JSON response
     */
    httpGetJSON<T = any>(relativeUrl: string, requestSettings?: RequestSettings): Promise<T>;
    /**
     * Sends an HTTP PUT request specifically formatted for JSON data.
     * This method automatically sets the 'Content-Type' and 'Accept' headers to 'application/json'.
     * Use this when sending JSON objects or when the server expects JSON content type.
     *
     * @param {string} relativeUrl The relative URL to send the request to
     * @param {any} value The JSON data to send in the request body
     * @param {RequestSettings} requestSettings Additional settings for the request (optional)
     * @returns {Promise<T>} A promise that resolves with the response data
     */
    httpPutJSON<T = any>(relativeUrl: string, value: any, requestSettings?: RequestSettings): Promise<T>;
    /**
     * Sends an HTTP PATCH request specifically formatted for JSON data.
     * This method automatically sets the 'Content-Type' and 'Accept' headers to 'application/json'.
     * Use this when sending JSON objects or when the server expects JSON content type.
     *
     * @param {string} relativeUrl The relative URL to send the request to
     * @param {any} value The JSON payload to send with the request
     * @param {RequestSettings} requestSettings Additional settings for the request (optional)
     * @returns {Promise<T>} A promise that resolves with the response data
     */
    httpPatchJSON<T = any>(relativeUrl: string, value: any, requestSettings?: RequestSettings): Promise<T>;
    /**
     * Sends an HTTP DELETE request specifically formatted for JSON data.
     * This method automatically sets the 'Content-Type' and 'Accept' headers to 'application/json'.
     *
     * @param {string} relativeUrl The relative URL for the request
     * @param {any} content The content to send with the request (optional)
     * @param {RequestSettings} requestSettings Additional settings for the request (optional)
     * @returns {Promise<T>} A promise that resolves with the response data
     */
    httpDeleteJSON<T = any>(relativeUrl: string, content?: any, requestSettings?: RequestSettings): Promise<T>;
    /**
     * Sends a generic HTTP PUT request to the specified relative address and returns the full response including data, headers, status code etc.
     *
     * @param {string} relativeAddress The relative address of the API endpoint
     * @param {any} value The data to be sent in the request body
     * @param {RequestSettings} requestSettings Additional settings for the request
     * @returns {Promise<Response<T>>} A promise that resolves with the full response including data, headers, status code etc.
     */
    httpPutFullResponse<T = any>(relativeAddress: string, value?: any, requestSettings?: RequestSettings): Promise<Response<T>>;
    /**
     * Sends an HTTP POST request with JSON data and returns the full response including data, headers, status code etc.
     *
     * @param {string} relativeAddress The relative address of the resource
     * @param {any} value The data to send with the request
     * @param {RequestSettings} requestSettings Additional settings for the request
     * @returns {Promise<Response<T>>} A promise that resolves with the full response including data, headers, status code etc.
     */
    httpPostJSONFullResponse<T = any>(relativeAddress: string, value: any, requestSettings?: RequestSettings): Promise<Response<T>>;
    /**
     * Deletes a resource and returns the full response including data, headers, status code etc.
     *
     * @param {string} relativeAddress The relative address of the resource
     * @param {any} content The content to send with the request
     * @param {RequestSettings} requestSettings Additional settings for the request
     * @returns {Promise<Response<T>>} A promise that resolves with the full response including data, headers, status code etc.
     */
    httpDeleteJSONFullResponse<T = any>(relativeAddress: string, content?: any, requestSettings?: RequestSettings): Promise<Response<T>>;
    private calculateAddress;
    private isObject;
    private mergeDeep;
    private combineSettings;
    /**
     * Prepares the address and settings for HTTP requests
     * @param relativeAddress The relative address for the request
     * @param requestSettings The request settings
     * @returns Object containing address and settings
     */
    private prepareRequest;
}
export {};