taler_merchant_donau.h (10338B)
1 /* 2 This file is part of TALER 3 Copyright (C) 2014-2024 Taler Systems SA 4 5 TALER is free software; you can redistribute it and/or modify it under the 6 terms of the GNU Affero General Public License as published by the Free Software 7 Foundation; either version 3, 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.LIB. If not, see <http://www.gnu.org/licenses/> 15 */ 16 /** 17 * @file taler_merchant_donau.h 18 * @brief Structs to interact with the donau. 19 * @author Bohdan Potuzhnyi 20 * @author Vlada Svirsh 21 */ 22 #ifndef _TALER_MERCHANT_DONAU_H 23 #define _TALER_MERCHANT_DONAU_H 24 25 #include <taler/taler_util.h> 26 #include <taler/taler_error_codes.h> 27 #include <taler/taler_exchange_service.h> 28 #include "taler_merchant_service.h" 29 #include <donau/donau_service.h> 30 #include <donau/donau_util.h> 31 #include <donau/donaudb_plugin.h> 32 33 /** 34 * Structure to hold charity details for the Donau service. 35 */ 36 struct TALER_MERCHANT_DONAU_Charity 37 { 38 /** 39 * name of the charity 40 */ 41 const char *name; 42 43 /** 44 * charity url 45 */ 46 const char *charity_url; 47 48 /** 49 * public key of the charity 50 */ 51 struct DONAU_CharityPublicKeyP charity_pub; 52 53 /** 54 * Max donation amount for this charitiy and @e current_year. 55 */ 56 struct TALER_Amount max_per_year; 57 58 /** 59 * Current amount of donation receipts for @e current_year. 60 */ 61 struct TALER_Amount receipts_to_date; 62 63 /** 64 * current year 65 */ 66 uint64_t current_year; 67 68 /** 69 * The unique identifier of the charity. 70 */ 71 uint64_t charity_id; 72 }; 73 74 75 /** 76 * Structure to hold Donau instance details from the database. 77 */ 78 struct TALER_MERCHANTDB_DonauInstance 79 { 80 /** 81 * Donau instance serial 82 */ 83 uint64_t donau_instance_serial; 84 85 /** 86 * The URL for the Donau instance. 87 */ 88 char *donau_url; 89 90 /** 91 * The name of the charity associated with the Donau instance. 92 */ 93 char *charity_name; 94 95 /** 96 * Pointer to the public key of the charity, used for cryptographic operations. 97 * This is represented as an EDDSA public key structure. 98 */ 99 struct DONAU_CharityPublicKeyP *charity_pub_key; 100 101 /** 102 * A unique identifier for the charity in the Donau instance. 103 */ 104 uint64_t charity_id; 105 106 /** 107 * The maximum allowable amount for donations to this charity in the current year. 108 * This is tracked for regulatory or internal business constraints. 109 */ 110 struct TALER_Amount charity_max_per_year; 111 112 /** 113 * The total amount of donations received by the charity in the current year. 114 * This field helps track progress toward the yearly donation limit. 115 */ 116 struct TALER_Amount charity_receipts_to_date; 117 118 /** 119 * The current year being tracked for donations. 120 * This is used to differentiate donation data between years. 121 */ 122 int64_t current_year; 123 124 /** 125 * A JSON object containing key information specific to the Donau instance, 126 * such as cryptographic keys or other relevant details. 127 */ 128 json_t *donau_keys_json; 129 }; 130 131 132 /** 133 * Callback function typically used by `select_donau_instances` to handle 134 * the details of each Donau instance retrieved from the database. 135 * 136 * @param cls Closure to pass additional context or data to the callback function. 137 * @param donau_instance_serial Serial number of the Donau instance in the merchant database. 138 * @param donau_url The URL of the Donau instance. 139 * @param charity_name The name of the charity associated with the Donau instance. 140 * @param charity_pub_key Pointer to the charity's public key used for cryptographic operations. 141 * @param charity_id The unique identifier for the charity within the Donau instance. 142 * @param charity_max_per_year Maximum allowed donations to the charity for the current year. 143 * @param charity_receipts_to_date Total donations received by the charity so far in the current year. 144 * @param current_year The year for which the donation data is being tracked. 145 * @param donau_keys_json JSON object containing additional key-related information for the Donau instance, NULL if not (yet) available. 146 */ 147 typedef void 148 (*TALER_MERCHANTDB_DonauInstanceCallback)( 149 void *cls, 150 uint64_t donau_instance_serial, 151 const char *donau_url, 152 const char *charity_name, 153 const struct DONAU_CharityPublicKeyP *charity_pub_key, 154 uint64_t charity_id, 155 const struct TALER_Amount *charity_max_per_year, 156 const struct TALER_Amount *charity_receipts_to_date, 157 int64_t current_year, 158 const json_t *donau_keys_json 159 ); 160 161 /** 162 * Callback function typically used by `select_donau_instances` to handle 163 * the details of each Donau instance retrieved from the database. 164 * 165 * @param cls Closure to pass additional context or data to the callback function. 166 * @param donau_url The URL of the Donau instance. 167 */ 168 typedef void 169 (*TALER_MERCHANTDB_DonauInstanceFilteredCallback)( 170 void *cls, 171 const char *donau_url 172 ); 173 174 /** 175 * SPECIFICATION FOR REQUESTS /donau 176 */ 177 178 /** 179 * Handle for a GET /donau operation. 180 */ 181 struct TALER_MERCHANT_DonauInstanceGetHandle; 182 183 /** 184 * Individual Donau instance details. 185 */ 186 struct TALER_MERCHANT_DonauInstanceEntry 187 { 188 /** 189 * Serial number of the Donau instance in merchant database. 190 */ 191 uint64_t donau_instance_serial; 192 193 /** 194 * The URL of the Donau service. 195 */ 196 const char *donau_url; 197 198 /** 199 * Name of the charity associated with the Donau instance. 200 */ 201 const char *charity_name; 202 203 /** 204 * Public key of the charity. 205 */ 206 struct DONAU_CharityPublicKeyP charity_pub_key; 207 208 /** 209 * ID of the charity on Donau. 210 */ 211 uint64_t charity_id; 212 213 /** 214 * Maximum donation amount per year allowed for the charity. 215 */ 216 struct TALER_Amount charity_max_per_year; 217 218 /** 219 * Total donations received by the charity in the current year. 220 */ 221 struct TALER_Amount charity_receipts_to_date; 222 223 /** 224 * The current year being tracked for donations. 225 */ 226 int64_t current_year; 227 228 /** 229 * Additional key information related to the Donau instance. 230 */ 231 const struct DONAU_Keys *donau_keys; 232 }; 233 234 /** 235 * Response for a GET /donau request. 236 */ 237 struct TALER_MERCHANT_DonauInstanceGetResponse 238 { 239 /** 240 * HTTP response details. 241 */ 242 struct TALER_MERCHANT_HttpResponse hr; 243 244 /** 245 * Details depending on the HTTP status. 246 */ 247 union 248 { 249 /** 250 * Details for #MHD_HTTP_OK. 251 */ 252 struct 253 { 254 /** 255 * Length of the @e donau_instances array. 256 */ 257 unsigned int donau_instances_length; 258 259 /** 260 * Details about the Donau instance. 261 */ 262 struct TALER_MERCHANT_DonauInstanceEntry *donau_instances; 263 } ok; 264 } details; 265 }; 266 267 /** 268 * Function called with the result of the GET /donau operation. 269 * 270 * @param cls closure 271 * @param dir response details 272 */ 273 typedef void 274 (*TALER_MERCHANT_DonauInstanceGetCallback)( 275 void *cls, 276 const struct TALER_MERCHANT_DonauInstanceGetResponse *dir); 277 278 /** 279 * Initiate the GET /donau request. 280 * 281 * @param ctx CURL context 282 * @param backend_url base URL for the backend 283 * @param cb callback function to handle the response 284 * @param cb_cls closure for the callback function 285 * @return the handle for the operation, or NULL on error 286 */ 287 struct TALER_MERCHANT_DonauInstanceGetHandle * 288 TALER_MERCHANT_donau_instances_get ( 289 struct GNUNET_CURL_Context *ctx, 290 const char *backend_url, 291 TALER_MERCHANT_DonauInstanceGetCallback cb, 292 void *cb_cls); 293 294 295 /** 296 * Cancel the GET /donau instances operation. 297 * 298 * @param dgh request to cancel. 299 */ 300 void 301 TALER_MERCHANT_donau_instances_get_cancel ( 302 struct TALER_MERCHANT_DonauInstanceGetHandle *dgh); 303 304 305 /** 306 * Handle for a POST /donau operation. 307 */ 308 struct TALER_MERCHANT_DonauInstancePostHandle; 309 310 311 /** 312 * Function called with the result of the POST /donau operation. 313 * 314 * @param cls closure 315 * @param hr HTTP response data 316 */ 317 typedef void 318 (*TALER_MERCHANT_DonauInstancePostCallback)( 319 void *cls, 320 const struct TALER_MERCHANT_HttpResponse *hr); 321 322 /** 323 * Post a new Donau instance. 324 * Sends a POST request to the backend to register a new Donau instance 325 * with the provided charity details. 326 * 327 * @param ctx the context 328 * @param backend_url the backend URL for the operation 329 * @param charity the details of the Donau charity to be posted 330 * @param auth_token the authentication token for the operation 331 * @param cb function to call with the operation result 332 * @param cb_cls closure for @a cb 333 * @return the instance handle, or NULL upon error 334 */ 335 struct TALER_MERCHANT_DonauInstancePostHandle * 336 TALER_MERCHANT_donau_instances_post ( 337 struct GNUNET_CURL_Context *ctx, 338 const char *backend_url, 339 const struct TALER_MERCHANT_DONAU_Charity *charity, 340 const char *auth_token, 341 TALER_MERCHANT_DonauInstancePostCallback cb, 342 void *cb_cls); 343 344 /** 345 * Cancel the POST /donau instances operation. 346 * This must not be called after the callback has been invoked. 347 * 348 * @param dph request to cancel 349 */ 350 void 351 TALER_MERCHANT_donau_instances_post_cancel ( 352 struct TALER_MERCHANT_DonauInstancePostHandle *dph); 353 354 /** 355 * Handle for a DELETE /donau/$charity_id operation. 356 */ 357 struct TALER_MERCHANT_DonauInstanceDeleteHandle; 358 359 /** 360 * Callback for DELETE /donau/$charity_id operation. 361 * 362 * @param cls Closure to pass context. 363 * @param hr HTTP response data. 364 */ 365 typedef void 366 (*TALER_MERCHANT_DonauInstanceDeleteCallback)( 367 void *cls, 368 const struct TALER_MERCHANT_HttpResponse *hr); 369 370 /** 371 * Initiates the DELETE /donau/$charity_id operation. 372 * 373 * @param ctx CURL context 374 * @param backend_url Base URL for the backend 375 * @param charity_id The ID of the charity to delete 376 * @param cb Callback function to handle the response 377 * @param cb_cls Closure for @a cb 378 * @return the handle for the operation, or NULL on error 379 */ 380 struct TALER_MERCHANT_DonauInstanceDeleteHandle * 381 TALER_MERCHANT_donau_instance_delete ( 382 struct GNUNET_CURL_Context *ctx, 383 const char *backend_url, 384 uint64_t charity_id, 385 TALER_MERCHANT_DonauInstanceDeleteCallback cb, 386 void *cb_cls); 387 388 /** 389 * Cancel the DELETE /donau/$charity_id operation. 390 * 391 * @param ddh Handle for the operation to cancel. 392 */ 393 void 394 TALER_MERCHANT_donau_instance_delete_cancel ( 395 struct TALER_MERCHANT_DonauInstanceDeleteHandle *ddh); 396 397 #endif