path: root/src/backend/taler-merchant-httpd_contract.h

/*
  This file is part of TALER
  (C) 2023 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 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 General Public License for more details.

  You should have received a copy of the GNU General Public License along with
  TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
*/
/**
 * @file taler-merchant-httpd_contract.h
 * @brief shared logic for contract terms handling
 * @author Christian Blättler
 */
#include "taler-merchant-httpd.h"


/**
 * Possible versions of the contract terms.
 */
enum TALER_MerchantContractVersion
{

  /**
   * Version 0
   */
  TALER_MCV_V0 = 0,

  /**
   * Version 1
   */
  TALER_MCV_V1 = 1
};

/**
* Possible input types for the contract terms.
*/
enum TALER_MerchantContractInputType
{

  /**
   * Input type coin
   */
  TALER_MCIT_COIN = 0,

  /**
   * Input type token
   */
  TALER_MCIT_TOKEN = 1
};

/**
* Contract input (part of the v1 contract terms).
*/
struct TALER_MerchantContractInput
{
  /**
  * Type of the input.
  */
  enum TALER_MerchantContractInputType type;

  union
  {
    /**
    * Coin-based input.
    */
    struct
    {
      /**
      * Price to be paid.
      */
      struct TALER_Amount price;
    } coin;

    /**
    * Token-based input.
    */
    struct
    {
      /**
      * Hash over the public key used to sign the type of subscription
      * token required.
      */
      struct TALER_TokenFamilyPublicKeyHash h_issuer;

      /**
      * Number of tokens of this type required. Defaults to one if the
      * field is not provided.
      */
      unsigned int number;
    } token;
  } details;
};

/**
* Possible output types for the contract terms.
*/
enum TALER_MerchantContractOutputType
{

  /**
   * Output type coin
   */
  TALER_MCOT_COIN = 0,

  /**
   * Output type token
   */
  TALER_MCOT_TOKEN = 1,

  /**
   * Output type tax-receipt
   */
  TALER_MCOT_TAX_RECEIPT = 2

};

/**
* Possible token output classes.
*/
enum TALER_MerchantContractOutputTokenClass
{

  /**
   * Token class subscription
   */
  TALER_MCOTC_SUBSCRIPTION = 0,

  /**
   * Token class discount
   */
  TALER_MCOTC_DISCOUNT = 1
};

/**
* Contract output (part of the v1 contract terms).
*/
struct TALER_MerchantContractOutput
{
  /**
  * Type of the output.
  */
  enum TALER_MerchantContractOutputType type;

  union
  {
    /**
    * Coin-based output.
    */
    struct {
      /**
      * Coins that will be yielded. This excludes any applicable withdraw fees.
      */
      struct TALER_Amount brutto_yield;

      /**
      * Base URL of the exchange that will issue the coins.
      */
      const char *exchange_url;
    } coin;

    /**
    * Tax-receipt output.
    */
    struct
    {
      /**
      * Base URL of the donation authority that will issue the tax receipt.
      */
      const char *donau_url;
    } tax_receipt;

    /**
    * Token-based output.
    */
    struct
    {
      /**
      * Label of the token authority in the 'token_authorities' array on the top-level.
      */
      const char *token_authority_label;

      /**
      * Must a wallet understand this token type to process contracts that
      * consume or yield it?
      */
      bool critical;

      /**
      * Class of token that will be yielded.
      */
      enum TALER_MerchantContractOutputTokenClass token_class;

      /**
      * Information about the class of token that will be yielded.
      */
      union
      {
        /**
        * Subscription token.
        */
        struct
        {
          /**
          * When does the subscription period start?
          */
          struct GNUNET_TIME_Absolute start_date;

          /**
          * When does the subscription period end?
          */
          struct GNUNET_TIME_Absolute end_date;

          /**
          * Array of domain names where this subscription can be safely used
          * (e.g. the issuer warrants that these sites will re-issue tokens of
          * this type if the respective contract says so). May contain "*" for
          * any domain or subdomain.
          */
          const char **trusted_domains;

          /**
          * Length of the @e trusted_domains array.
          */
          unsigned int trusted_domains_len;
        } subscription;

        /**
        * Discount token.
        */
        struct
        {
          /**
          * Array of domain names where this discount token is intended to be
          * used. May contain "*" for any domain or subdomain. Users should be
          * warned about sites proposing to consume discount tokens of this
          * type that are not in this list that the merchant is accepting a
          * coupon from a competitor and thus may be attaching different
          * semantics (like get 20% discount for my competitors 30% discount
          * token).
          */
          const char **expected_domains;

          /**
          * Length of the @e expected_domains array.
          */
          unsigned int expected_domains_len;

        } discount;
      } details;
    } token;
  } details;
};

/**
* Contract choice (part of the v1 contract terms).
*/
struct TALER_MerchantContractChoice
{
  /**
  * Summary of the order.
  */
  const char *summary;

  /**
  * Internationalized summary.
  */
  json_t *summary_i18n;

  /**
  * URL that will show that the order was successful
  * after it has been paid for.
  */
  const char *fulfillment_url;

  /**
  * Message shown to the customer after paying for the order.
  * Either fulfillment_url or fulfillment_message must be specified.
  */
  const char *fulfillment_message;

  /**
  * Map from IETF BCP 47 language tags to localized fulfillment messages.
  */
  json_t *fulfillment_message_i18n;

  /**
  * Array of products that are part of the purchase.
  */
  const json_t *products;

  /**
  * List of inputs the wallet must provision (all of them) to satisfy the
  * conditions for the contract.
  */
  struct TALER_MerchantContractInput *inputs;

  /**
  * Length of the @e inputs array.
  */
  unsigned int inputs_len;

  /**
  * List of outputs the merchant promises to yield (all of them) once
  * the contract is paid.
  */
  struct TALER_MerchantContractOutput *ouputs;

  /**
  * Length of the @e outputs array.
  */
  unsigned int outputs_len;
}