Class ApiRequest

constructor

• new ApiRequest(url: string, uriEncodeMethod?: TUriEncodeFunction): ApiRequest

  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.

  Parameters

  • url: string

    The request URL to initialize the ApiRequest with.
  • OptionaluriEncodeMethod: TUriEncodeFunction

    Optional. A custom method for encoding URI components.

  Returns ApiRequest

  Since

  1.1.12

  Version

  2018-10-20

Parameters

URL

Static ReadonlySignature

Static ReadonlySignatureNonce

Static ReadonlyTimestamp

EncodeURIMethod

• get EncodeURIMethod(): TUriEncodeFunction

  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 TUriEncodeFunction

  The function used to encode URIs.

  Since

  1.1.12

  Version

  2018-10-20

FullUrlWithoutSignature

• get FullUrlWithoutSignature(): string

  Gets the complete URL by concatenating the base URL (this.URL) with the URL path excluding the signature (this.UrlWithoutSignature).

  Returns string

  The full URL string without the signature parameter.

  Since

  1.1.17

  Version

  2019-02-20

UrlWithoutSignature

• get UrlWithoutSignature(): string

  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 string

  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

AddParameter

• AddParameter(name: string, val?: string): ApiRequest

  Adds a parameter to the request.

  Parameters

  • name: string

    The name of the parameter to add.
  • Optionalval: string

    The value of the parameter. Optional.

  Returns ApiRequest

  The current instance for method chaining.

AddSignatureNonce

• AddSignatureNonce(): ApiRequest

  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 ApiRequest

  The current instance of the API request for method chaining.

AddTimestamp

• AddTimestamp(): ApiRequest

  Adds the current timestamp as a parameter to the API request.

  Returns ApiRequest

  The current instance of the API request for method chaining.

Make

• Make(
      accessSecret: string,
      signatureMethod: TStringSignatureMethod,
  ): Promise<string>

  Constructs a signed API request URL by generating a signature using the provided secret and signature method.

  Parameters

  • accessSecret: string

    The secret key used to sign the request.
  • signatureMethod: TStringSignatureMethod

    A function that generates a signature from the string to sign and the access secret.

  Returns Promise<string>

  A promise that resolves to the fully constructed and signed request URL as a string.

  Throws

  If the URL is invalid or does not start with "http".

StaticVerify

• Verify(
      secret: string,
      url: string,
      signatureMethod: TStringSignatureMethod,
      encodeURIMethod?: (str: string) => string,
      decodeURIMethod?: (str: string) => string,
  ): Promise<true | ApiRequestVerifyError>

  Verifies the authenticity and validity of an API request based on its signature and timestamp.

  Parameters

  • secret: string

    The secret key used for signature verification.
  • url: string

    The full URL containing the query parameters to verify.
  • signatureMethod: TStringSignatureMethod

    A function that generates a signature from the URL and secret.
  • encodeURIMethod: (str: string) => string = EncodeByRFC3986

    (Optional) Function to encode URI components, defaults to EncodeByRFC3986.

    • • (str: string): string

      • Encodes a string according to RFC 3986 specifications.

        This function first applies encodeURIComponent to the input string, then further encodes the characters !, *, (, ), and ' to ensure full compliance with RFC 3986.

        Parameters

        • str: string

          The input string to encode.

        Returns string

        The RFC 3986-compliant encoded string.

        See

        https://tools.ietf.org/html/rfc3986

        Since

        1.1.6

        Version

        2021-12-07

  • decodeURIMethod: (str: string) => string = DecodeByRFC3986

    (Optional) Function to decode URI components, defaults to DecodeByRFC3986.

    • • (str: string): string

      • Decodes a URI component string according to RFC 3986 specifications.

        This function first replaces specific percent-encoded characters (%21, %2A, %28, %29, %27) with their corresponding literal characters (!, *, (, ), ') before applying decodeURIComponent. This ensures compatibility with RFC 3986, which allows these characters to remain unencoded in URI components.

        Parameters

        • str: string

          The percent-encoded URI component string to decode.

        Returns string

        The decoded string, with RFC 3986 reserved characters properly handled.

        Since

        1.1.11

        Version

        2021-12-07

  Returns Promise<true | ApiRequestVerifyError>

  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.