/********************************************************************
 * @author:      Kaven
 * @email:       kaven@wuwenkai.com
 * @website:     http://blog.kaven.xyz
 * @file:        [Kaven-Basic] /src/libs/class/ApiRequest.ts
 * @create:      2018-08-30 16:06:50.928
 * @modify:      2025-07-02 18:03:34.437
 * @version:     6.0.0
 * @times:       94
 * @lines:       294
 * @copyright:   Copyright © 2018-2025 Kaven. All Rights Reserved.
 * @description: [description]
 * @license:
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 ********************************************************************/
import { DecodeByRFC3986, EncodeByRFC3986 } from "../core/RFC3986";
import { ApiRequestVerifyError } from "../enum/ApiRequestVerifyError";
import { TStringObject, TStringOrUndefined, TStringSignatureMethod, TUriEncodeFunction } from "../type/basic";
/**
 * Represents an API request builder that supports parameter management,
 * signature generation, and verification for secure API communication.
 *
 * This class provides methods to construct API request URLs with parameters,
 * generate cryptographic signatures, and verify signed requests. It is designed
 * to be compatible with signature-based authentication schemes.
 *
 * @remarks
 * - The "Action" field has been removed since version 1.1.12.
 * - The class automatically adds `Timestamp` and `SignatureNonce` parameters when making requests.
 * - Signature generation and verification rely on user-provided methods.
 *
 * @example
 * ```typescript
 * const api = new ApiRequest("https://example.com/api");
 * api.AddParameter("foo", "bar");
 * const signedUrl = await api.Make(secret, signatureMethod);
 * ```
 *
 * @public
 *
 * @since 1.1.6
 * @version 2021-12-09
 */
export declare class ApiRequest {
    static readonly Timestamp = "Timestamp";
    static readonly SignatureNonce = "SignatureNonce";
    static readonly Signature = "Signature";
    URL: string;
    Parameters: TStringObject<TStringOrUndefined>;
    private uriEncodeMethod?;
    /**
     * Initializes a new instance of the ApiRequest class.
     *
     * Parses the provided URL, extracts its origin and pathname, and initializes the URL property.
     * If the URL contains query parameters, they are parsed and added to the Parameters object using AddParameter.
     * Optionally accepts a custom URI encoding method.
     *
     * @param url - The request URL to initialize the ApiRequest with.
     * @param uriEncodeMethod - Optional. A custom method for encoding URI components.
     *
     * @since 1.1.12
     * @version 2018-10-20
     */
    constructor(url: string, uriEncodeMethod?: TUriEncodeFunction);
    /**
     * Adds a parameter to the request.
     *
     * @param name - The name of the parameter to add.
     * @param val - The value of the parameter. Optional.
     * @returns The current instance for method chaining.
     */
    AddParameter(name: string, val?: string): this;
    /**
     * Adds the current timestamp as a parameter to the API request.
     *
     * @returns The current instance of the API request for method chaining.
     */
    AddTimestamp(): this;
    /**
     * Adds a randomly generated signature nonce parameter to the API request.
     *
     * This method generates a random string of 6 characters and adds it as the value
     * for the `SignatureNonce` parameter. Useful for ensuring request uniqueness and
     * preventing replay attacks.
     *
     * @returns The current instance of the API request for method chaining.
     */
    AddSignatureNonce(): this;
    /**
     * Constructs a signed API request URL by generating a signature using the provided secret and signature method.
     *
     * @param accessSecret - The secret key used to sign the request.
     * @param signatureMethod - A function that generates a signature from the string to sign and the access secret.
     * @returns A promise that resolves to the fully constructed and signed request URL as a string.
     * @throws {Error} If the URL is invalid or does not start with "http".
     */
    Make(accessSecret: string, signatureMethod: TStringSignatureMethod): Promise<string>;
    /**
     * Verifies the authenticity and validity of an API request based on its signature and timestamp.
     *
     * @param secret - The secret key used for signature verification.
     * @param url - The full URL containing the query parameters to verify.
     * @param signatureMethod - A function that generates a signature from the URL and secret.
     * @param encodeURIMethod - (Optional) Function to encode URI components, defaults to EncodeByRFC3986.
     * @param decodeURIMethod - (Optional) Function to decode URI components, defaults to DecodeByRFC3986.
     * @returns A promise that resolves to `true` if verification succeeds, or an `ApiRequestVerifyError` if verification fails.
     *
     * @remarks
     * The verification process checks for the existence and validity of the timestamp and signature,
     * ensures the request is not expired (within 60 seconds), and validates the signature.
     */
    static Verify(secret: string, url: string, signatureMethod: TStringSignatureMethod, encodeURIMethod?: typeof EncodeByRFC3986, decodeURIMethod?: typeof DecodeByRFC3986): Promise<true | ApiRequestVerifyError>;
    /**
     * Gets the URL query string constructed from the current `Parameters` object,
     * excluding any signature-related parameters. The query string is built by
     * sorting the parameter keys, encoding both keys and values, and concatenating
     * them in the standard URL format. If a parameter value is `undefined`, only
     * the key is included without a value assignment.
     *
     * @returns The constructed URL query string (starting with '?' or '&' as appropriate),
     *          with all keys and values URI-encoded.
     *
     * @since 1.1.12
     * @version 2018-10-20
     */
    get UrlWithoutSignature(): string;
    /**
     * Gets the complete URL by concatenating the base URL (`this.URL`) with the URL path excluding the signature (`this.UrlWithoutSignature`).
     *
     * @returns The full URL string without the signature parameter.
     *
     * @since 1.1.17
     * @version 2019-02-20
     */
    get FullUrlWithoutSignature(): string;
    /**
     * Gets the URI encoding method to be used for requests.
     *
     * If a custom encoding method (`encodeURIMethod`) is defined on the instance, it returns that method.
     * Otherwise, it defaults to using the `EncodeByRFC3986` method.
     *
     * @returns The function used to encode URIs.
     *
     * @since 1.1.12
     * @version 2018-10-20
     */
    get EncodeURIMethod(): TUriEncodeFunction;
}
//# sourceMappingURL=ApiRequest.d.ts.map