/*
   This file is part of TALER
   Copyright (C) 2014-2025 Taler Systems SA

   TALER is free software; you can redistribute it and/or modify it under the
   terms of the GNU Affero General Public License as published by the Free Software
   Foundation; either version 3, or (at your option) any later version.

   TALER is distributed in the hope that it will be useful, but WITHOUT ANY
   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
   A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.

   You should have received a copy of the GNU Affero General Public License along with
   TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
 */
/**
 * @file include/taler/exchange/common.h
 * @brief C interface of libtalerexchange, a C library to use exchange's HTTP API
 *        This library is not thread-safe, all APIs must only be used from a single thread.
 *        This library calls abort() if it runs out of memory. Be aware of these limitations.
 * @author Sree Harsha Totakura <sreeharsha@totakura.in>
 * @author Christian Grothoff
 * @author Özgür Kesim
 */
#ifndef _TALER_EXCHANGE__COMMON_H
#define _TALER_EXCHANGE__COMMON_H

#include <jansson.h>
#include <taler/taler_util.h>
#include <taler/taler_error_codes.h>
#include <gnunet/gnunet_curl_lib.h>


/**
 * Maximum number of options that can be set in one set_options
 * call. Used as a dummy for "infinite" in the varargs case.
 */
#define TALER_EXCHANGE_COMMON_OPTIONS_ARRAY_MAX_SIZE UINT_MAX


/**
 * Global options for HTTP requests made to the exchange.
 */
enum TALER_EXCHANGE_GlobalOptions
{

  /**
   * Use defaults.
   */
  TALER_EXCHANGE_GO_NONE = 0,

  /**
   * Force use of HTTP/1.1.
   */
  TALER_EXCHANGE_GO_FORCE_HTTP1_1 = 1,

};


/**
 * Set global options for HTTP requests made with libtalerexchange.
 *
 * @param go global options to use
 */
void
TALER_EXCHANGE_setup (enum TALER_EXCHANGE_GlobalOptions go);


/**
 * Forward declaration for the exchange's set of online signing keys and
 * denomination keys.  Several endpoint headers reference this type in their
 * function signatures; declaring it here keeps those headers self-contained
 * when they are included early (e.g. to override a *_RESULT_CLOSURE macro).
 * Both types are fully defined in get-keys.h.
 */
struct TALER_EXCHANGE_Keys;
struct TALER_EXCHANGE_DenomPublicKey;

/**
 * Forward declaration for the input to a melt operation, defined in
 * post-reveal-melt.h but also referenced (by pointer) from post-melt.h.
 */
struct TALER_EXCHANGE_MeltInput;


/**
 * General information about the HTTP response we obtained
 * from the exchange for a request.
 */
struct TALER_EXCHANGE_HttpResponse
{

  /**
   * The complete JSON reply. NULL if we failed to parse the
   * reply (too big, invalid JSON).
   */
  const json_t *reply;

  /**
   * Set to the human-readable 'hint' that is optionally
   * provided by the exchange together with errors. NULL
   * if no hint was provided or if there was no error.
   */
  const char *hint;

  /**
   * HTTP status code for the response.  0 if the
   * HTTP request failed and we did not get any answer, or
   * if the answer was invalid and we set @a ec to a
   * client-side error code.
   */
  unsigned int http_status;

  /**
   * Taler error code.  #TALER_EC_NONE if everything was
   * OK.  Usually set to the "code" field of an error
   * response, but may be set to values created at the
   * client side, for example when the response was
   * not in JSON format or was otherwise ill-formed.
   */
  enum TALER_ErrorCode ec;

};


/**
 * Information returned when a client needs to pass
 * a KYC check before the transaction may succeed.
 */
struct TALER_EXCHANGE_KycNeededRedirect
{

  /**
   * Hash of the payto-URI of the account to KYC;
   */
  struct TALER_NormalizedPaytoHashP h_payto;

  /**
   * Public key needed to access the KYC state of
   * this account. All zeros if a wire transfer
   * is required first to establish the key.
   */
  union TALER_AccountPublicKeyP account_pub;

  /**
   * Legitimization requirement that the merchant should use
   * to check for its KYC status, 0 if not known.
   */
  uint64_t requirement_row;

  /**
   * Set to true if the KYC AUTH public key known to the exchange does not
   * match the merchant public key associated with the deposit operation.
   */
  bool bad_kyc_auth;
};


/**
 * We received an #MHD_HTTP_UNAVAILABLE_FOR_LEGAL_REASONS response code.
 * Parse the JSON response and initialize the @a uflr object.
 *
 * @param[out] uflr data structure to initialize
 * @param j JSON response to parse
 * @return #GNUNET_OK on success
 */
enum GNUNET_GenericReturnValue
TALER_EXCHANGE_parse_451 (struct TALER_EXCHANGE_KycNeededRedirect *uflr,
                          const json_t *j);


/**
 * Information about a coin to be deposited into a purse or reserve.
 */
struct TALER_EXCHANGE_PurseDeposit
{
  /**
   * Age commitment data, might be NULL.
   */
  const struct TALER_AgeCommitmentProof *age_commitment_proof;

  /**
   * Private key of the coin.
   */
  struct TALER_CoinSpendPrivateKeyP coin_priv;

  /**
   * Signature proving the validity of the coin.
   */
  struct TALER_DenominationSignature denom_sig;

  /**
   * Hash of the denomination's public key.
   */
  struct TALER_DenominationHashP h_denom_pub;

  /**
   * Amount of the coin to transfer into the purse.
   */
  struct TALER_Amount amount;

};


#endif
