/**
 * HTTP service for sending requests to backend endpoints
 *
 * The {@link HttpClient} is the primary interface for making HTTP requests
 * within the Lime platform.
 *
 * By default, all requests expect JSON responses. For other content types
 * (text, binary data, etc.), set the `responseType` in {@link HttpOptions}.
 *
 * All methods throw {@link HttpResponseError} on HTTP errors (4xx, 5xx status codes).
 *
 * @example Read, create, update, and remove data
 * ```ts
 * import { PlatformServiceName } from '@limetech/lime-web-components';
 *
 * const http = platform.get(PlatformServiceName.Http);
 *
 * const users = await http.get('my_addon/users', { params: { active: 'true' } });
 *
 * const created = await http.post('my_addon/users', {
 *     name: 'John Doe',
 *     email: 'john@example.com',
 * });
 *
 * await http.patch(`my_addon/users/${created.id}`, {
 *     email: 'john.doe@example.com',
 * });
 *
 * await http.delete(`my_addon/users/${created.id}`);
 * ```
 *
 * @public
 * @group HTTP
 */
export interface HttpClient {
    /**
     * Sends a GET request to retrieve data from the server
     *
     * @param url - Relative URL to the resource (e.g., 'my_addon/endpoint').
     * The URL is relative to the Lime CRM base URL.
     * @param options - Optional {@link HttpOptions} for query parameters, headers, or response type
     * @returns Promise resolving to the response data. Type depends on {@link HttpOptions.responseType}
     *
     * @throws {@link HttpResponseError} when the server responds with an error status (4xx, 5xx)
     *
     * @example Get users that match query parameters
     * ```ts
     * import { PlatformServiceName } from '@limetech/lime-web-components';
     *
     * const http = platform.get(PlatformServiceName.Http);
     *
     * const users = await http.get('my_addon/users', {
     *     params: { active: 'true', limit: '10' },
     * });
     * ```
     */
    get(url: string, options?: HttpOptions): Promise<any>;
    /**
     * Sends a POST request to create new data on the server
     *
     * @param url - Relative URL to the resource (e.g., 'my_addon/endpoint')
     * @param data - Payload to send in the request body. Will be JSON-encoded by default.
     * @param options - Optional {@link HttpOptions} for query parameters, headers, or response type
     * @returns Promise resolving to the response data. Type depends on {@link HttpOptions.responseType}
     *
     * @throws {@link HttpResponseError} when the server responds with an error status (4xx, 5xx)
     *
     * @example Create a user
     * ```ts
     * import { PlatformServiceName } from '@limetech/lime-web-components';
     *
     * const http = platform.get(PlatformServiceName.Http);
     *
     * const newUser = await http.post('my_addon/users', {
     *     name: 'Jane Smith',
     *     email: 'jane@example.com',
     * });
     * ```
     */
    post(url: string, data?: object, options?: HttpOptions): Promise<any>;
    /**
     * Sends a PATCH request to partially update existing data on the server
     *
     * @param url - Relative URL to the resource (e.g., 'my_addon/users/123')
     * @param data - Partial payload containing only the fields to update
     * @param options - Optional {@link HttpOptions} for query parameters, headers, or response type
     * @returns Promise resolving to the response data. Type depends on {@link HttpOptions.responseType}
     *
     * @throws {@link HttpResponseError} when the server responds with an error status (4xx, 5xx)
     *
     * @example Update one field on a user
     * ```ts
     * import { PlatformServiceName } from '@limetech/lime-web-components';
     *
     * const http = platform.get(PlatformServiceName.Http);
     *
     * await http.patch('my_addon/users/123', {
     *     email: 'newemail@example.com',
     * });
     * ```
     */
    patch(url: string, data?: object, options?: HttpOptions): Promise<any>;
    /**
     * Sends a PUT request to replace existing data on the server
     *
     * @param url - Relative URL to the resource (e.g., 'my_addon/users/123')
     * @param data - Complete payload to replace the existing resource
     * @param options - Optional {@link HttpOptions} for query parameters, headers, or response type
     * @returns Promise resolving to the response data. Type depends on {@link HttpOptions.responseType}
     *
     * @throws {@link HttpResponseError} when the server responds with an error status (4xx, 5xx)
     *
     * @example Replace a user
     * ```ts
     * import { PlatformServiceName } from '@limetech/lime-web-components';
     *
     * const http = platform.get(PlatformServiceName.Http);
     *
     * await http.put('my_addon/users/123', {
     *     name: 'Jane Doe',
     *     email: 'jane@example.com',
     *     role: 'admin',
     * });
     * ```
     */
    put(url: string, data?: object, options?: HttpOptions): Promise<any>;
    /**
     * Sends a DELETE request to remove data from the server
     *
     * @param url - Relative URL to the resource (e.g., 'my_addon/users/123')
     * @param options - Optional {@link HttpOptions} for query parameters or headers
     * @returns Promise resolving to the response data. Type depends on {@link HttpOptions.responseType}
     *
     * @throws {@link HttpResponseError} when the server responds with an error status (4xx, 5xx)
     *
     * @example Remove a user
     * ```ts
     * import { PlatformServiceName } from '@limetech/lime-web-components';
     *
     * const http = platform.get(PlatformServiceName.Http);
     *
     * await http.delete('my_addon/users/123');
     * ```
     */
    delete(url: string, options?: HttpOptions): Promise<any>;
}
/**
 * Configuration options for HTTP requests
 *
 * @example Set parameters, headers, and response type
 * ```ts
 * import {
 *     HttpOptions,
 *     PlatformServiceName,
 * } from '@limetech/lime-web-components';
 *
 * const http = platform.get(PlatformServiceName.Http);
 *
 * const options: HttpOptions = {
 *     params: { search: 'John', limit: '10' },
 *     headers: { 'X-Custom-Header': 'value' },
 *     responseType: 'json',
 * };
 *
 * const users = await http.get('my_addon/users', options);
 * ```
 *
 * @public
 * @group HTTP
 */
export interface HttpOptions {
    /**
     * Query parameters to append to the URL
     *
     * Parameters will be URL-encoded and appended to the request URL.
     *
     * @example Repeat a parameter with an array value
     * ```ts
     * import { HttpParams, PlatformServiceName } from '@limetech/lime-web-components';
     *
     * const http = platform.get(PlatformServiceName.Http);
     *
     * const params: HttpParams = {
     *     active: 'true',
     *     role: ['admin', 'user'],
     * };
     *
     * // Requests my_addon/users?active=true&role=admin&role=user
     * const users = await http.get('my_addon/users', { params });
     * ```
     */
    params?: HttpParams;
    /**
     * Additional HTTP headers to include in the request
     *
     * @example Send extra headers with a request
     * ```ts
     * import {
     *     HttpHeaders,
     *     PlatformServiceName,
     * } from '@limetech/lime-web-components';
     *
     * const http = platform.get(PlatformServiceName.Http);
     *
     * const headers: HttpHeaders = {
     *     Authorization: 'Bearer token123',
     *     'Accept-Language': 'en-US',
     * };
     *
     * const data = await http.get('my_addon/endpoint', { headers });
     * ```
     */
    headers?: HttpHeaders;
    /**
     * Expected response data type. Defaults to 'json'
     *
     * - `json`: Parse response as JSON (default)
     * - `text`: Get response as plain text string
     * - `blob`: Get response as binary Blob (for file downloads)
     * - `arraybuffer`: Get response as ArrayBuffer (for binary data processing)
     *
     * @example Download a PDF file as a blob
     * ```ts
     * import { PlatformServiceName } from '@limetech/lime-web-components';
     *
     * const http = platform.get(PlatformServiceName.Http);
     *
     * const report: Blob = await http.get('my_addon/report.pdf', {
     *     responseType: 'blob',
     * });
     *
     * const url = URL.createObjectURL(report);
     * window.open(url);
     * ```
     */
    responseType?: HttpResponseType;
}
/**
 * URL query parameters for HTTP requests
 *
 * Key-value pairs that will be appended to the request URL as query string.
 * Array values will be repeated for the same parameter name.
 *
 * @public
 * @group HTTP
 */
export interface HttpParams {
    [param: string]: string | string[];
}
/**
 * HTTP headers for requests
 *
 * Custom headers to include in the HTTP request. Array values will be
 * joined as comma-separated values for the same header name.
 *
 * @public
 * @group HTTP
 */
export interface HttpHeaders {
    [header: string]: string | string[];
}
/**
 * Response data type for HTTP requests
 *
 * Determines how the response body will be parsed and returned.
 *
 * @public
 * @group HTTP
 */
export type HttpResponseType = 'text' | 'json' | 'arraybuffer' | 'blob';
/**
 * HTTP method constants
 *
 * Standard HTTP methods as constant values. Useful for type-safe method
 * selection in custom HTTP utilities.
 *
 * @example Pick a method in a custom request helper
 * ```ts
 * import { HttpMethod, PlatformServiceName } from '@limetech/lime-web-components';
 *
 * const http = platform.get(PlatformServiceName.Http);
 *
 * function sendUser(method: HttpMethod) {
 *     const user = { name: 'Jane Smith', email: 'jane@example.com' };
 *
 *     if (method === HttpMethod.Put) {
 *         return http.put('my_addon/users/123', user);
 *     }
 *
 *     return http.post('my_addon/users', user);
 * }
 *
 * const saved = await sendUser(HttpMethod.Put);
 * ```
 *
 * @public
 * @group HTTP
 */
export declare const HttpMethod: {
    readonly Get: "GET";
    readonly Post: "POST";
    readonly Put: "PUT";
    readonly Delete: "DELETE";
    readonly Patch: "PATCH";
};
/**
 * Type definition for HTTP methods
 *
 * Union type of all values in the {@link HttpMethod} constant.
 *
 * @public
 * @group HTTP
 */
export type HttpMethod = (typeof HttpMethod)[keyof typeof HttpMethod];
/**
 * Error thrown when an HTTP request fails
 *
 * This error is thrown by {@link HttpClient} methods when the server responds
 * with an error status code (4xx or 5xx).
 *
 * @example Handle a failed request by status code
 * ```ts
 * import {
 *     HttpResponseError,
 *     PlatformServiceName,
 * } from '@limetech/lime-web-components';
 *
 * const http = platform.get(PlatformServiceName.Http);
 *
 * // `HttpResponseError` is an interface, so the name is the only way to spot it.
 * function isHttpResponseError(error: unknown): error is HttpResponseError {
 *     return error instanceof Error && error.name === 'HttpResponseError';
 * }
 *
 * try {
 *     const data = await http.get('my_addon/data');
 * } catch (error) {
 *     if (!isHttpResponseError(error)) {
 *         throw error;
 *     }
 *
 *     if (error.status === 404) {
 *         console.error('Resource not found');
 *     } else if (error.status >= 500) {
 *         console.error('Server error:', error.status);
 *     }
 *
 *     const body = await error.response.text();
 *     console.error('Response body:', body);
 * }
 * ```
 *
 * @public
 * @group HTTP
 */
export interface HttpResponseError extends Error {
    name: 'HttpResponseError';
    /**
     * HTTP status code from the failed response
     */
    status: number;
    /**
     * The full Response object from the failed request
     *
     * Use this to access response headers or read the response body:
     * ```typescript
     * const body = await error.response.text();
     * const contentType = error.response.headers.get('content-type');
     * ```
     */
    response: Response;
}