post-private-products.h (18836B)
1 /* 2 This file is part of TALER 3 Copyright (C) 2014-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-products.h 19 * @brief C interface for the POST /private/products endpoint 20 * @author Christian Grothoff 21 */ 22 #ifndef _TALER_MERCHANT__POST_PRIVATE_PRODUCTS_H 23 #define _TALER_MERCHANT__POST_PRIVATE_PRODUCTS_H 24 25 #include <taler/merchant/common.h> 26 27 28 /** 29 * Possible options for the POST /private/products request. 30 */ 31 enum TALER_MERCHANT_PostPrivateProductsOption 32 { 33 /** 34 * End of list of options. 35 */ 36 TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_END = 0, 37 38 /** 39 * Internationalized descriptions (JSON). 40 */ 41 TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_DESCRIPTION_I18N, 42 43 /** 44 * Tax information (JSON array). 45 */ 46 TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_TAXES, 47 48 /** 49 * Storage location (JSON). 50 */ 51 TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_ADDRESS, 52 53 /** 54 * Expected restock time. 55 */ 56 TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_NEXT_RESTOCK, 57 58 /** 59 * Minimum age requirement. 60 */ 61 TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_MINIMUM_AGE, 62 63 /** 64 * Category IDs. 65 */ 66 TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_CATEGORIES, 67 68 /** 69 * Value and fractional part of total stock. 70 */ 71 TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_TOTAL_STOCK, 72 73 /** 74 * Value part of total stock (-1 for unlimited). 75 */ 76 TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_TOTAL_STOCK_VAL, 77 78 /** 79 * Fractional part of total stock. 80 */ 81 TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_TOTAL_STOCK_FRAC, 82 83 /** 84 * Whether fractional quantities are allowed. 85 */ 86 TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_UNIT_ALLOW_FRACTION, 87 88 /** 89 * Precision level for fractions. 90 */ 91 TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_UNIT_PRECISION_LEVEL, 92 93 /** 94 * Explicit product name (distinct from description). 95 */ 96 TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_PRODUCT_NAME, 97 98 /** 99 * Product image (base64-encoded data URL). 100 */ 101 TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_IMAGE, 102 103 /** 104 * Product group ID. 105 */ 106 TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_PRODUCT_GROUP_ID, 107 108 /** 109 * Money pot ID. 110 */ 111 TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_MONEY_POT_ID, 112 113 /** 114 * Whether the price is net (before tax). 115 */ 116 TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_PRICE_IS_NET 117 118 }; 119 120 121 /** 122 * Value for an option for the POST /private/products request. 123 */ 124 struct TALER_MERCHANT_PostPrivateProductsOptionValue 125 { 126 127 /** 128 * Type of the option being set. 129 */ 130 enum TALER_MERCHANT_PostPrivateProductsOption option; 131 132 /** 133 * Specific option value. 134 */ 135 union 136 { 137 138 /** 139 * Value if @e option is 140 * #TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_DESCRIPTION_I18N. 141 */ 142 const json_t *description_i18n; 143 144 /** 145 * Value if @e option is 146 * #TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_TAXES. 147 */ 148 const json_t *taxes; 149 150 /** 151 * Value if @e option is 152 * #TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_ADDRESS. 153 */ 154 const json_t *address; 155 156 /** 157 * Value if @e option is 158 * #TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_NEXT_RESTOCK. 159 */ 160 struct GNUNET_TIME_Timestamp next_restock; 161 162 /** 163 * Value if @e option is 164 * #TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_MINIMUM_AGE. 165 */ 166 uint32_t minimum_age; 167 168 /** 169 * Value if @e option is 170 * #TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_CATEGORIES. 171 */ 172 struct 173 { 174 unsigned int num; 175 const uint64_t *cats; 176 } categories; 177 178 /** 179 * Value if @e option is 180 * #TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_TOTAL_STOCK. 181 */ 182 struct 183 { 184 /** 185 * Value if @e option is 186 * #TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_TOTAL_STOCK_VAL. 187 * -1 for infinite stock. 188 */ 189 int64_t val; 190 191 /** 192 * Value if @e option is 193 * #TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_TOTAL_STOCK_FRAC. 194 */ 195 uint32_t frac; 196 } total_stock; 197 198 /** 199 * Value if @e option is 200 * #TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_UNIT_ALLOW_FRACTION. 201 */ 202 bool unit_allow_fraction; 203 204 /** 205 * Value if @e option is 206 * #TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_UNIT_PRECISION_LEVEL. 207 */ 208 uint32_t unit_precision_level; 209 210 /** 211 * Value if @e option is 212 * #TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_PRODUCT_NAME. 213 */ 214 const char *product_name; 215 216 /** 217 * Value if @e option is 218 * #TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_IMAGE. 219 */ 220 const char *image; 221 222 /** 223 * Value if @e option is 224 * #TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_PRODUCT_GROUP_ID. 225 */ 226 uint64_t product_group_id; 227 228 /** 229 * Value if @e option is 230 * #TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_MONEY_POT_ID. 231 */ 232 uint64_t money_pot_id; 233 234 /** 235 * Value if @e option is 236 * #TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_PRICE_IS_NET. 237 */ 238 bool price_is_net; 239 240 } details; 241 242 }; 243 244 245 /** 246 * Handle for a POST /private/products request. 247 */ 248 struct TALER_MERCHANT_PostPrivateProductsHandle; 249 250 251 /** 252 * Response details for a POST /private/products request. 253 */ 254 struct TALER_MERCHANT_PostPrivateProductsResponse 255 { 256 257 /** 258 * HTTP response details. 259 */ 260 struct TALER_MERCHANT_HttpResponse hr; 261 262 }; 263 264 265 /** 266 * Terminate the list of the options. 267 * 268 * @return the terminating object of struct TALER_MERCHANT_PostPrivateProductsOptionValue 269 */ 270 #define TALER_MERCHANT_post_private_products_option_end_() \ 271 (const struct TALER_MERCHANT_PostPrivateProductsOptionValue) \ 272 { \ 273 .option = TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_END \ 274 } 275 276 /** 277 * Set internationalized descriptions. 278 * 279 * @param d descriptions JSON object 280 * @return representation of the option 281 */ 282 #define TALER_MERCHANT_post_private_products_option_description_i18n(d) \ 283 (const struct TALER_MERCHANT_PostPrivateProductsOptionValue) \ 284 { \ 285 .option = TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_DESCRIPTION_I18N \ 286 , \ 287 .details.description_i18n = (d) \ 288 } 289 290 /** 291 * Set tax information. 292 * 293 * @param t taxes JSON array 294 * @return representation of the option 295 */ 296 #define TALER_MERCHANT_post_private_products_option_taxes(t) \ 297 (const struct TALER_MERCHANT_PostPrivateProductsOptionValue) \ 298 { \ 299 .option = TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_TAXES, \ 300 .details.taxes = (t) \ 301 } 302 303 /** 304 * Set storage address. 305 * 306 * @param a address JSON object 307 * @return representation of the option 308 */ 309 #define TALER_MERCHANT_post_private_products_option_address(a) \ 310 (const struct TALER_MERCHANT_PostPrivateProductsOptionValue) \ 311 { \ 312 .option = TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_ADDRESS, \ 313 .details.address = (a) \ 314 } 315 316 /** 317 * Set expected restock time. 318 * 319 * @param r restock timestamp 320 * @return representation of the option 321 */ 322 #define TALER_MERCHANT_post_private_products_option_next_restock(r) \ 323 (const struct TALER_MERCHANT_PostPrivateProductsOptionValue) \ 324 { \ 325 .option = TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_NEXT_RESTOCK, \ 326 .details.next_restock = (r) \ 327 } 328 329 /** 330 * Set minimum age requirement. 331 * 332 * @param a minimum age (0 for none) 333 * @return representation of the option 334 */ 335 #define TALER_MERCHANT_post_private_products_option_minimum_age(a) \ 336 (const struct TALER_MERCHANT_PostPrivateProductsOptionValue) \ 337 { \ 338 .option = TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_MINIMUM_AGE, \ 339 .details.minimum_age = (a) \ 340 } 341 342 /** 343 * Set category IDs. 344 * 345 * @param n number of categories 346 * @param c array of category IDs 347 * @return representation of the option 348 */ 349 #define TALER_MERCHANT_post_private_products_option_categories(n,c) \ 350 (const struct TALER_MERCHANT_PostPrivateProductsOptionValue) \ 351 { \ 352 .option = TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_CATEGORIES, \ 353 .details.categories = { .num = (n), .cats = (c) } \ 354 } 355 356 /** 357 * Set fractional part of total stock. 358 * 359 * @param f fractional part 360 * @return representation of the option 361 */ 362 #define TALER_MERCHANT_post_private_products_option_total_stock_frac(f) \ 363 (const struct TALER_MERCHANT_PostPrivateProductsOptionValue) \ 364 { \ 365 .option = TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_TOTAL_STOCK_FRAC, \ 366 .details.total_stock.frac = (f) \ 367 } 368 369 /** 370 * Set fractional part of total stock. 371 * 372 * @param s total stock amount 373 * @return representation of the option 374 */ 375 #define TALER_MERCHANT_post_private_products_option_total_stock_val(s) \ 376 (const struct TALER_MERCHANT_PostPrivateProductsOptionValue) \ 377 { \ 378 .option = TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_TOTAL_STOCK_VAL, \ 379 .details.total_stock.val = (s) \ 380 } 381 382 /** 383 * Set stock. 384 * 385 * @param s stock value 386 * @param f fractional stock 387 * @return representation of the option 388 */ 389 #define TALER_MERCHANT_post_private_products_option_total_stock(s,f) \ 390 (const struct TALER_MERCHANT_PostPrivateProductsOptionValue) \ 391 { \ 392 .option = TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_TOTAL_STOCK, \ 393 .details.total_stock.val = (s), \ 394 .details.total_stock.frac = (f) \ 395 } 396 397 /** 398 * Set whether fractional quantities are allowed. 399 * 400 * @param b true to allow fractions 401 * @return representation of the option 402 */ 403 #define TALER_MERCHANT_post_private_products_option_unit_allow_fraction(b) \ 404 (const struct TALER_MERCHANT_PostPrivateProductsOptionValue) \ 405 { \ 406 .option = \ 407 TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_UNIT_ALLOW_FRACTION, \ 408 .details.unit_allow_fraction = (b) \ 409 } 410 411 /** 412 * Set precision level for fractional quantities. 413 * 414 * @param p precision level 415 * @return representation of the option 416 */ 417 #define TALER_MERCHANT_post_private_products_option_unit_precision_level(p) \ 418 (const struct TALER_MERCHANT_PostPrivateProductsOptionValue) \ 419 { \ 420 .option = \ 421 TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_UNIT_PRECISION_LEVEL, \ 422 .details.unit_precision_level = (p) \ 423 } 424 425 426 /** 427 * Set explicit product name (distinct from description). 428 * 429 * @param n product name string 430 * @return representation of the option 431 */ 432 #define TALER_MERCHANT_post_private_products_option_product_name(n) \ 433 (const struct TALER_MERCHANT_PostPrivateProductsOptionValue) \ 434 { \ 435 .option = TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_PRODUCT_NAME, \ 436 .details.product_name = (n) \ 437 } 438 439 /** 440 * Set product image (base64-encoded data URL). 441 * 442 * @param i image string 443 * @return representation of the option 444 */ 445 #define TALER_MERCHANT_post_private_products_option_image(i) \ 446 (const struct TALER_MERCHANT_PostPrivateProductsOptionValue) \ 447 { \ 448 .option = TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_IMAGE, \ 449 .details.image = (i) \ 450 } 451 452 /** 453 * Set product group ID. 454 * 455 * @param g product group ID 456 * @return representation of the option 457 */ 458 #define TALER_MERCHANT_post_private_products_option_product_group_id(g) \ 459 (const struct TALER_MERCHANT_PostPrivateProductsOptionValue) \ 460 { \ 461 .option = \ 462 TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_PRODUCT_GROUP_ID, \ 463 .details.product_group_id = (g) \ 464 } 465 466 /** 467 * Set money pot ID. 468 * 469 * @param m money pot ID 470 * @return representation of the option 471 */ 472 #define TALER_MERCHANT_post_private_products_option_money_pot_id(m) \ 473 (const struct TALER_MERCHANT_PostPrivateProductsOptionValue) \ 474 { \ 475 .option = \ 476 TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_MONEY_POT_ID, \ 477 .details.money_pot_id = (m) \ 478 } 479 480 /** 481 * Set whether the price is net (before tax). 482 * 483 * @param b true if price is net 484 * @return representation of the option 485 */ 486 #define TALER_MERCHANT_post_private_products_option_price_is_net(b) \ 487 (const struct TALER_MERCHANT_PostPrivateProductsOptionValue) \ 488 { \ 489 .option = \ 490 TALER_MERCHANT_POST_PRIVATE_PRODUCTS_OPTION_PRICE_IS_NET, \ 491 .details.price_is_net = (b) \ 492 } 493 494 495 /** 496 * Set the requested options for the operation. 497 * 498 * @param ppph the request to set the options for 499 * @param num_options length of the @a options array 500 * @param options an array of options 501 * @return #GNUNET_OK on success, 502 * #GNUNET_NO on failure, 503 * #GNUNET_SYSERR on internal error 504 */ 505 enum GNUNET_GenericReturnValue 506 TALER_MERCHANT_post_private_products_set_options_ ( 507 struct TALER_MERCHANT_PostPrivateProductsHandle *ppph, 508 unsigned int num_options, 509 const struct TALER_MERCHANT_PostPrivateProductsOptionValue *options); 510 511 512 /** 513 * Set the requested options for the operation. 514 * 515 * @param ppph the request to set the options for 516 * @param ... the list of the options 517 * @return #GNUNET_OK on success, 518 * #GNUNET_NO on failure, 519 * #GNUNET_SYSERR on internal error 520 */ 521 #define TALER_MERCHANT_post_private_products_set_options(ppph,...) \ 522 TALER_MERCHANT_post_private_products_set_options_ ( \ 523 ppph, \ 524 TALER_MERCHANT_COMMON_OPTIONS_ARRAY_MAX_SIZE, \ 525 ((const struct TALER_MERCHANT_PostPrivateProductsOptionValue[]) \ 526 {__VA_ARGS__, TALER_MERCHANT_post_private_products_option_end_ () } \ 527 )) 528 529 530 /** 531 * Set up POST /private/products operation. 532 * Note that you must explicitly start the operation after 533 * possibly setting options. 534 * 535 * @param ctx the context 536 * @param url base URL of the merchant backend 537 * @param product_id identifier for the new product 538 * @param description human-readable product description 539 * @param unit unit of measurement 540 * @param num_prices length of the @e prices array 541 * @param prices new unit prices 542 * @return handle to operation 543 */ 544 struct TALER_MERCHANT_PostPrivateProductsHandle * 545 TALER_MERCHANT_post_private_products_create ( 546 struct GNUNET_CURL_Context *ctx, 547 const char *url, 548 const char *product_id, 549 const char *description, 550 const char *unit, 551 unsigned int num_prices, 552 const struct TALER_Amount prices[static num_prices]); 553 554 555 #ifndef TALER_MERCHANT_POST_PRIVATE_PRODUCTS_RESULT_CLOSURE 556 /** 557 * Type of the closure used by 558 * the #TALER_MERCHANT_PostPrivateProductsCallback. 559 */ 560 #define TALER_MERCHANT_POST_PRIVATE_PRODUCTS_RESULT_CLOSURE void 561 #endif /* TALER_MERCHANT_POST_PRIVATE_PRODUCTS_RESULT_CLOSURE */ 562 563 /** 564 * Callback for a POST /private/products request. 565 * 566 * @param cls closure 567 * @param ppr response details 568 */ 569 typedef void 570 (*TALER_MERCHANT_PostPrivateProductsCallback)( 571 TALER_MERCHANT_POST_PRIVATE_PRODUCTS_RESULT_CLOSURE *cls, 572 const struct TALER_MERCHANT_PostPrivateProductsResponse *ppr); 573 574 575 /** 576 * Start POST /private/products operation. 577 * 578 * @param[in,out] ppph operation to start 579 * @param cb function to call with the merchant's result 580 * @param cb_cls closure for @a cb 581 * @return status code, #TALER_EC_NONE on success 582 */ 583 enum TALER_ErrorCode 584 TALER_MERCHANT_post_private_products_start ( 585 struct TALER_MERCHANT_PostPrivateProductsHandle *ppph, 586 TALER_MERCHANT_PostPrivateProductsCallback cb, 587 TALER_MERCHANT_POST_PRIVATE_PRODUCTS_RESULT_CLOSURE *cb_cls); 588 589 590 /** 591 * Cancel POST /private/products operation. This function must not be 592 * called by clients after the TALER_MERCHANT_PostPrivateProductsCallback 593 * has been invoked (as in those cases it'll be called internally by the 594 * implementation already). 595 * 596 * @param[in] ppph operation to cancel 597 */ 598 void 599 TALER_MERCHANT_post_private_products_cancel ( 600 struct TALER_MERCHANT_PostPrivateProductsHandle *ppph); 601 602 603 #endif /* _TALER_MERCHANT__POST_PRIVATE_PRODUCTS_H */