/*
   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 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/get-aml-OFFICER_PUB-measures.h
 * @brief C interface for GET /aml/$OFFICER_PUB/measures
 * @author Christian Grothoff
 */
#ifndef _TALER_EXCHANGE__GET_AML_OFFICER_PUB_MEASURES_H
#define _TALER_EXCHANGE__GET_AML_OFFICER_PUB_MEASURES_H

#include <taler/exchange/common.h>

/**
 * Handle for an operation to GET /aml/$OFFICER_PUB/measures.
 */
struct TALER_EXCHANGE_GetAmlMeasuresHandle;


/**
 * Information about a root measure available at the exchange.
 * Corresponds to a MeasureInformation object in AvailableMeasureSummary.
 */
struct TALER_EXCHANGE_GetAmlMeasuresMeasureInfo
{
  /**
   * Name of the measure (map key in the response).
   */
  const char *measure_name;

  /**
   * Name of the KYC check.
   */
  const char *check_name;

  /**
   * Name of the AML program. Can be NULL.
   * Since protocol v30.
   */
  const char *prog_name;

  /**
   * Context for the check. Can be NULL.
   */
  const json_t *context;

  /**
   * Operation that this measure relates to. Can be NULL if unknown.
   * Since protocol v21.
   */
  const char *operation_type;

  /**
   * True if this measure can be undertaken voluntarily.
   * Since protocol vATTEST.
   */
  bool voluntary;
};


/**
 * Information about an AML program available at the exchange.
 * Corresponds to an AmlProgramRequirement object.
 */
struct TALER_EXCHANGE_GetAmlMeasuresProgramRequirement
{
  /**
   * Name of the AML program (map key in the response).
   */
  const char *prog_name;

  /**
   * Description of what the AML program does.
   */
  const char *description;

  /**
   * Array of required field names in the context to run this AML program.
   */
  const char **contexts;

  /**
   * Length of the @e contexts array.
   */
  size_t contexts_length;

  /**
   * Array of required attribute names in the input of this AML program.
   */
  const char **inputs;

  /**
   * Length of the @e inputs array.
   */
  size_t inputs_length;
};


/**
 * Information about a KYC check available at the exchange.
 * Corresponds to a KycCheckInformation object.
 */
struct TALER_EXCHANGE_GetAmlMeasuresCheckInfo
{
  /**
   * Name of the KYC check (map key in the response).
   */
  const char *check_name;

  /**
   * Description of the KYC check.
   */
  const char *description;

  /**
   * Internationalized description of the KYC check. Can be NULL.
   */
  const json_t *description_i18n;

  /**
   * Name of the root measure that is to be taken when this check fails.
   */
  const char *fallback;

  /**
   * Array with the names of the fields that CONTEXT must provide as inputs
   * to this check.
   */
  const char **requires;

  /**
   * Length of the @e requires array.
   */
  size_t requires_length;

  /**
   * Array of attribute names the check will output.
   */
  const char **outputs;

  /**
   * Length of the @e outputs array.
   */
  size_t outputs_length;
};


/**
 * A KYC rule from the default rule set.
 * Corresponds to a KycRule object in default_rules.
 * Since protocol v28.
 */
struct TALER_EXCHANGE_GetAmlMeasuresKycRule
{
  /**
   * Type of operation to which the rule applies.
   */
  enum TALER_KYCLOGIC_KycTriggerEvent operation_type;

  /**
   * Name of the configuration section this rule originates from.
   * Can be NULL.
   */
  const char *rule_name;

  /**
   * The threshold amount that triggers the measures.
   */
  struct TALER_Amount threshold;

  /**
   * Over which duration should the threshold be computed.
   */
  struct GNUNET_TIME_Relative timeframe;

  /**
   * Length of the @e measures array.
   */
  size_t measures_length;

  /**
   * Array of names of measures to apply.
   */
  const char **measures;

  /**
   * Display priority for this rule.
   */
  int64_t display_priority;

  /**
   * True if the rule should be exposed to the client.
   */
  bool exposed;

  /**
   * True if all measures need to be satisfied (AND combinator),
   * false if any measure is sufficient (OR combinator).
   */
  bool is_and_combinator;
};


/**
 * Response from a GET /aml/$OFFICER_PUB/measures request.
 */
struct TALER_EXCHANGE_GetAmlMeasuresResponse
{
  /**
   * HTTP response data
   */
  struct TALER_EXCHANGE_HttpResponse hr;

  /**
   * Response details depending on the HTTP status.
   */
  union
  {
    /**
     * Details if HTTP status is #MHD_HTTP_OK.
     */
    struct
    {
      /**
       * Available root measures. Length in @e roots_length.
       */
      const struct TALER_EXCHANGE_GetAmlMeasuresMeasureInfo *roots;

      /**
       * Length of the @e roots array.
       */
      size_t roots_length;

      /**
       * Available AML programs. Length in @e programs_length.
       */
      const struct TALER_EXCHANGE_GetAmlMeasuresProgramRequirement *programs;

      /**
       * Length of the @e programs array.
       */
      size_t programs_length;

      /**
       * Available KYC checks. Length in @e checks_length.
       */
      const struct TALER_EXCHANGE_GetAmlMeasuresCheckInfo *checks;

      /**
       * Length of the @e checks array.
       */
      size_t checks_length;

      /**
       * Default KYC rules applied to new accounts.
       * Since protocol v28.
       */
      const struct TALER_EXCHANGE_GetAmlMeasuresKycRule *default_rules;

      /**
       * Length of the @e default_rules array.
       */
      size_t default_rules_length;

    } ok;
  } details;

};


#ifndef TALER_EXCHANGE_GET_AML_MEASURES_RESULT_CLOSURE
/**
 * Type of the closure used by
 * the #TALER_EXCHANGE_GetAmlMeasuresCallback.
 */
#define TALER_EXCHANGE_GET_AML_MEASURES_RESULT_CLOSURE void
#endif /* TALER_EXCHANGE_GET_AML_MEASURES_RESULT_CLOSURE */

/**
 * Type of the function that receives the result of a
 * GET /aml/$OFFICER_PUB/measures request.
 *
 * @param cls closure
 * @param result result returned by the HTTP server
 */
typedef void
(*TALER_EXCHANGE_GetAmlMeasuresCallback)(
  TALER_EXCHANGE_GET_AML_MEASURES_RESULT_CLOSURE *cls,
  const struct TALER_EXCHANGE_GetAmlMeasuresResponse *result);


/**
 * Set up GET /aml/$OPUB/measures operation.
 * Note that you must explicitly start the operation after setup.
 *
 * @param ctx the context
 * @param url base URL of the exchange
 * @param officer_priv private key of the officer
 * @return handle to operation
 */
struct TALER_EXCHANGE_GetAmlMeasuresHandle *
TALER_EXCHANGE_get_aml_measures_create (
  struct GNUNET_CURL_Context *ctx,
  const char *url,
  const struct TALER_AmlOfficerPrivateKeyP *officer_priv);


/**
 * Start GET /aml/$OPUB/measures operation.
 *
 * @param[in,out] amh operation to start
 * @param cb function to call with the exchange's result
 * @param cb_cls closure for @a cb
 * @return status code, #TALER_EC_NONE on success
 */
enum TALER_ErrorCode
TALER_EXCHANGE_get_aml_measures_start (
  struct TALER_EXCHANGE_GetAmlMeasuresHandle *amh,
  TALER_EXCHANGE_GetAmlMeasuresCallback cb,
  TALER_EXCHANGE_GET_AML_MEASURES_RESULT_CLOSURE *cb_cls);


/**
 * Cancel GET /aml/$OPUB/measures operation.  This function
 * must not be called by clients after the
 * TALER_EXCHANGE_GetAmlMeasuresCallback has been invoked
 * (as in those cases it'll be called internally by the
 * implementation already).
 *
 * @param[in] amh operation to cancel
 */
void
TALER_EXCHANGE_get_aml_measures_cancel (
  struct TALER_EXCHANGE_GetAmlMeasuresHandle *amh);


#endif /* _TALER_EXCHANGE__GET_AML_OFFICER_PUB_MEASURES_H */
