merchant

Merchant backend to process payments, run by merchants
Log | Files | Refs | Submodules | README | LICENSE

post-private-fountains.h (4906B)


      1 /*
      2   This file is part of TALER
      3   Copyright (C) 2026 Taler Systems SA
      4 
      5   TALER is free software; you can redistribute it and/or modify it under the
      6   terms of the GNU Lesser General Public License as published by the Free Software
      7   Foundation; either version 2.1, or (at your option) any later version.
      8 
      9   TALER is distributed in the hope that it will be useful, but WITHOUT ANY
     10   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
     11   A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more details.
     12 
     13   You should have received a copy of the GNU Lesser General Public License along with
     14   TALER; see the file COPYING.LGPL.  If not, see
     15   <http://www.gnu.org/licenses/>
     16 */
     17 /**
     18  * @file src/include/taler/merchant/post-private-fountains.h
     19  * @brief C interface for the POST /private/fountains endpoint (DD 98)
     20  * @author Bohdan Potuzhnyi
     21  */
     22 #ifndef _TALER_MERCHANT__POST_PRIVATE_FOUNTAINS_H
     23 #define _TALER_MERCHANT__POST_PRIVATE_FOUNTAINS_H
     24 
     25 #include <taler/merchant/common.h>
     26 
     27 
     28 /**
     29  * Withdrawal rights of a fountain for one token family (DD 98).
     30  */
     31 struct TALER_MERCHANT_FountainGrant
     32 {
     33   /**
     34    * Slug of the token family this grant refers to.
     35    */
     36   const char *token_family_slug;
     37 
     38   /**
     39    * Maximum number of tokens blind-signed per issue-key validity
     40    * period for this family.
     41    */
     42   uint64_t tokens_per_period_limit;
     43 
     44   /**
     45    * Number of tokens the wallet should aim to hold per period;
     46    * at most @e tokens_per_period_limit.
     47    */
     48   uint64_t tokens_per_period_stash;
     49 
     50   /**
     51    * Maximum number of future issue keys in addition to the current key.
     52    * No key may start after now + key_window_size * duration.
     53    * Each successive key is selected just after the previous key expires,
     54    * using the token family's normal duration and rounding rules. The
     55    * advertised window can be shorter if family bounds or rounding prevent
     56    * further coverage. Zero allows only the current key.
     57    */
     58   uint32_t key_window_size;
     59 };
     60 
     61 
     62 /**
     63  * Handle for a POST /private/fountains request.
     64  */
     65 struct TALER_MERCHANT_PostPrivateFountainsHandle;
     66 
     67 
     68 /**
     69  * Response details for a POST /private/fountains request.
     70  */
     71 struct TALER_MERCHANT_PostPrivateFountainsResponse
     72 {
     73 
     74   /**
     75    * HTTP response details.
     76    */
     77   struct TALER_MERCHANT_HttpResponse hr;
     78 
     79   /**
     80    * Details depending on the HTTP status.
     81    */
     82   union
     83   {
     84     /**
     85      * Details on #MHD_HTTP_OK.
     86      */
     87     struct
     88     {
     89       /**
     90        * Public identifier of the new fountain.
     91        */
     92       const char *fountain_id;
     93 
     94       /**
     95        * Bearer credential of the new fountain, Crockford Base32.
     96        * Returned exactly once; the backend stores only its hash.
     97        */
     98       const char *fountain_secret;
     99     } ok;
    100   } details;
    101 
    102 };
    103 
    104 
    105 #ifndef TALER_MERCHANT_POST_PRIVATE_FOUNTAINS_RESULT_CLOSURE
    106 /**
    107  * Type of the closure used by
    108  * the #TALER_MERCHANT_PostPrivateFountainsCallback.
    109  */
    110 #define TALER_MERCHANT_POST_PRIVATE_FOUNTAINS_RESULT_CLOSURE void
    111 #endif /* TALER_MERCHANT_POST_PRIVATE_FOUNTAINS_RESULT_CLOSURE */
    112 
    113 /**
    114  * Callback for a POST /private/fountains request.
    115  *
    116  * @param cls closure
    117  * @param pfr response details
    118  */
    119 typedef void
    120 (*TALER_MERCHANT_PostPrivateFountainsCallback)(
    121   TALER_MERCHANT_POST_PRIVATE_FOUNTAINS_RESULT_CLOSURE *cls,
    122   const struct TALER_MERCHANT_PostPrivateFountainsResponse *pfr);
    123 
    124 
    125 /**
    126  * Set up POST /private/fountains operation.
    127  * Note that you must explicitly start the operation.
    128  *
    129  * @param ctx the context
    130  * @param url base URL of the merchant backend
    131  * @param description description of the fountain
    132  * @param poll_freq how often wallets should re-poll the fountain info
    133  * @param num_grants length of the @a grants array
    134  * @param grants withdrawal rights of the fountain
    135  * @return handle to operation
    136  */
    137 struct TALER_MERCHANT_PostPrivateFountainsHandle *
    138 TALER_MERCHANT_post_private_fountains_create (
    139   struct GNUNET_CURL_Context *ctx,
    140   const char *url,
    141   const char *description,
    142   struct GNUNET_TIME_Relative poll_freq,
    143   unsigned int num_grants,
    144   const struct TALER_MERCHANT_FountainGrant *grants);
    145 
    146 
    147 /**
    148  * Start POST /private/fountains operation.
    149  *
    150  * @param[in,out] ppfh operation to start
    151  * @param cb function to call with the merchant's result
    152  * @param cb_cls closure for @a cb
    153  * @return status code, #TALER_EC_NONE on success
    154  */
    155 enum TALER_ErrorCode
    156 TALER_MERCHANT_post_private_fountains_start (
    157   struct TALER_MERCHANT_PostPrivateFountainsHandle *ppfh,
    158   TALER_MERCHANT_PostPrivateFountainsCallback cb,
    159   TALER_MERCHANT_POST_PRIVATE_FOUNTAINS_RESULT_CLOSURE *cb_cls);
    160 
    161 
    162 /**
    163  * Cancel POST /private/fountains operation.  This function must not be
    164  * called by clients after the callback has been invoked.
    165  *
    166  * @param[in] ppfh operation to cancel
    167  */
    168 void
    169 TALER_MERCHANT_post_private_fountains_cancel (
    170   struct TALER_MERCHANT_PostPrivateFountainsHandle *ppfh);
    171 
    172 
    173 #endif /* _TALER_MERCHANT__POST_PRIVATE_FOUNTAINS_H */