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

  TALER is free software; you can redistribute it and/or modify it under the
  terms of the GNU Lesser General Public License as published by the Free Software
  Foundation; either version 2.1, 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 Lesser General Public License for more details.

  You should have received a copy of the GNU Lesser General Public License along with
  TALER; see the file COPYING.LGPL.  If not, see
  <http://www.gnu.org/licenses/>
*/
/**
 * @file include/taler/taler-merchant/get-management-instances-INSTANCE-kyc.h
 * @brief C interface for GET /management/instances/$INSTANCE/kyc of the merchant backend
 * @author Christian Grothoff
 */
#ifndef _TALER_MERCHANT__GET_MANAGEMENT_INSTANCES_INSTANCE_KYC_H
#define _TALER_MERCHANT__GET_MANAGEMENT_INSTANCES_INSTANCE_KYC_H

#include <taler/taler-merchant/common.h>


/**
 * Handle for a GET /management/instances/$INSTANCE/kyc (or /private/kyc) request.
 */
struct TALER_MERCHANT_KycGetHandle;


/**
 * Information about KYC actions the merchant still must perform.
 */
struct TALER_MERCHANT_AccountKycRedirectDetail
{

  /**
   * Access token the user needs to start a KYC process,
   * all zero if a KYC auth transfer must be made first.
   */
  struct TALER_AccountAccessTokenP access_token;

  /**
   * Base URL of the exchange this is about.
   */
  const char *exchange_url;

  /**
   * Our bank wire account this is about.
   */
  struct TALER_FullPayto payto_uri;

  /**
   * Array of length @e limits_array with (exposed) limits that apply to the
   * account.
   */
  const struct TALER_EXCHANGE_AccountLimit *limits;

  /**
   * Array of payto://-URIs with instructions for wire
   * transfers to perform a KYC auth wire transfer for
   * the given account. Needed if @e kyc_url is NULL
   * and @e limits are to be passed.
   */
  struct TALER_FullPayto *payto_kycauths;

  /**
   * Length of the @e limits array.
   */
  unsigned int limits_length;

  /**
   * Length of the @e payto_kycauths array.
   */
  unsigned int pkycauth_length;

  /**
   * HTTP status code returned by the exchange when we asked for
   * information about the KYC status.
   * 0 if there was no response at all.
   */
  unsigned int exchange_http_status;

  /**
   * Error code indicating errors the exchange
   * returned, or #TALER_EC_NONE for none.
   */
  enum TALER_ErrorCode exchange_code;

  /**
   * Set to true if @e access_token was not given.
   */
  bool no_access_token;

  /**
   * Set to true if the merchant backend could not
   * get the exchanges ``/keys`` and thus could not
   * determine default limits or determine an
   * @e auth_conflict.
   */
  bool no_keys;

  /**
   * Set to true if the given account cannot to KYC at the given exchange
   * because no wire method exists that could be used to do the KYC auth wire
   * transfer.
   */
  bool auth_conflict;
};


/**
 * Response details for a KYC status request.
 */
struct TALER_MERCHANT_KycResponse
{

  /**
   * HTTP response details.
   */
  struct TALER_MERCHANT_HttpResponse hr;

  /**
   * Details depending on the HTTP status code.
   */
  union
  {

    /**
     * Details on #MHD_HTTP_OK (all accounts passed KYC).
     */
    struct
    {

      /**
       * Number of KYC redirect details in @a kycs.
       */
      unsigned int kycs_length;

      /**
       * Array of KYC redirect details for accounts requiring KYC.
       */
      const struct TALER_MERCHANT_AccountKycRedirectDetail *kycs;

    } ok;

  } details;

};


/**
 * Callback for a KYC status request.
 *
 * @param cls closure
 * @param kr response details
 */
typedef void
(*TALER_MERCHANT_KycGetCallback)(
  void *cls,
  const struct TALER_MERCHANT_KycResponse *kr);


/**
 * Issue a GET /private/kyc request to check KYC status for accounts
 * of the current instance.
 *
 * @param ctx CURL context to use
 * @param backend_url base URL of the merchant backend
 * @param h_wire hash of the wire account to check, or NULL for all
 * @param exchange_url URL of the exchange to check with, or NULL for any
 * @param lpt long-poll target (what status to wait for)
 * @param timeout long-polling timeout
 * @param cb callback to invoke with the result
 * @param cb_cls closure for @a cb
 * @return handle for the request, NULL on hard error
 */
struct TALER_MERCHANT_KycGetHandle *
TALER_MERCHANT_kyc_get (
  struct GNUNET_CURL_Context *ctx,
  const char *backend_url,
  const struct TALER_MerchantWireHashP *h_wire,
  const char *exchange_url,
  enum TALER_EXCHANGE_KycLongPollTarget lpt,
  struct GNUNET_TIME_Relative timeout,
  TALER_MERCHANT_KycGetCallback cb,
  void *cb_cls);


/**
 * Issue a GET /management/instances/$INSTANCE/kyc request to check KYC
 * status for accounts of a specific instance (management access required).
 *
 * @param ctx CURL context to use
 * @param backend_url base URL of the merchant backend
 * @param instance_id identifier of the instance to check
 * @param h_wire hash of the wire account to check, or NULL for all
 * @param exchange_url URL of the exchange to check with, or NULL for any
 * @param lpt long-poll target (what status to wait for)
 * @param timeout long-polling timeout
 * @param cb callback to invoke with the result
 * @param cb_cls closure for @a cb
 * @return handle for the request, NULL on hard error
 */
struct TALER_MERCHANT_KycGetHandle *
TALER_MERCHANT_management_kyc_get (
  struct GNUNET_CURL_Context *ctx,
  const char *backend_url,
  const char *instance_id,
  const struct TALER_MerchantWireHashP *h_wire,
  const char *exchange_url,
  enum TALER_EXCHANGE_KycLongPollTarget lpt,
  struct GNUNET_TIME_Relative timeout,
  TALER_MERCHANT_KycGetCallback cb,
  void *cb_cls);


/**
 * Cancel a KYC status request.
 *
 * @param[in] kyc handle to cancel
 */
void
TALER_MERCHANT_kyc_get_cancel (
  struct TALER_MERCHANT_KycGetHandle *kyc);


#endif
