[taler-merchant] 105/277: API design for /transfers

[gnunet]

This is an automated email from the git hooks/post-receive script.

grothoff pushed a commit to branch master
in repository merchant.

commit a0c0df48c4de7207451c3fc16cc3f5b658d50a8d
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Mon May 11 00:26:06 2020 +0200

    API design for /transfers
---
 src/include/taler_merchant_service.h | 268 ++++++++++++++++++++++++++---------
 1 file changed, 199 insertions(+), 69 deletions(-)

diff --git a/src/include/taler_merchant_service.h 
b/src/include/taler_merchant_service.h
index 170e627..1e62f4e 100644
--- a/src/include/taler_merchant_service.h
+++ b/src/include/taler_merchant_service.h
@@ -1104,6 +1104,7 @@ TALER_MERCHANT_product_delete_cancel (
 /**
  * Handle to a POST /orders operation
  */
+// FIXME: rename: Operation => Handle!
 struct TALER_MERCHANT_PostOrdersOperation;
 
 /**
@@ -2146,22 +2147,19 @@ TALER_MERCHANT_post_order_refund_cancel (
   struct TALER_MERCHANT_OrderRefundHandle *orh);
 
 
-/* *********************   OLD ************************** */
-
-
-/* ********************* /track/transfer *********************** */
+/* ********************* /transfers *********************** */
 
 /**
- * @brief Handle to a /track/transfer operation at a merchant's backend.
+ * @brief Handle to a POST /transfers operation at a merchant's backend.
  */
-struct TALER_MERCHANT_TrackTransferHandle;
+struct TALER_MERCHANT_PostTransfersHandle;
 
 /**
  * Information about the _total_ amount that was paid back
  * by the exchange for a given h_contract_terms, by _one_ wire
  * transfer.
  */
-struct TALER_MERCHANT_TrackTransferDetails
+struct TALER_MERCHANT_TrackTransferDetail
 {
 
   /**
@@ -2182,14 +2180,18 @@ struct TALER_MERCHANT_TrackTransferDetails
 };
 
 /**
- * Callbacks of this type are used to work the result of submitting a 
/track/transfer request to a merchant
+ * Callbacks of this type are used to work the result of submitting a
+ * POST /transfers request to a merchant
  *
  * @param cls closure
  * @param hr HTTP response details
- * @param sign_key exchange key used to sign @a json, or NULL
- * @param h_wire hash of the wire transfer address the transfer went to, or 
NULL on error
- * @param total_amount total amount of the wire transfer, or NULL if the 
exchange could
- *             not provide any @a wtid (set only if @a http_status is 
#MHD_HTTP_OK)
+ * @param execution_time when did the transfer happen (according to the 
exchange),
+ *          #GNUNET_TIME_UNIT_FOREVER_ABS if the transfer did not yet happen 
or if
+ *          we have no data from the exchange about it
+ * @param total_amount total amount of the wire transfer, or NULL if the 
exchange did
+ *             not provide any details
+ * @param wire_fee how much did the exchange charge in terms of wire fees, or 
NULL
+ *             if the exchange did not provide any details
  * @param details_length length of the @a details array
  * @param details array with details about the combined transactions
  */
@@ -2197,125 +2199,177 @@ typedef void
 (*TALER_MERCHANT_TrackTransferCallback) (
   void *cls,
   const struct TALER_MERCHANT_HttpResponse *hr,
-  const struct TALER_ExchangePublicKeyP *sign_key,
-  const struct GNUNET_HashCode *h_wire,
+  struct GNUNET_TIME_Absolute execution_time,
   const struct TALER_Amount *total_amount,
+  const struct TALER_Amount *wire_fee,
   unsigned int details_length,
-  const struct TALER_MERCHANT_TrackTransferDetails *details);
+  const struct TALER_MERCHANT_TrackTransferDetails details[]);
 
 
 /**
- * Request backend to return deposits associated with a given wtid.
+ * Request backend to remember that we received the given
+ * wire transfer and to request details about the aggregated
+ * transactions from the exchange.
  *
  * @param ctx execution context
  * @param backend_url base URL of the backend
- * @param wire_method wire method used for the wire transfer
+ * @param credit_amount how much money did we receive (without wire fee)
  * @param wtid base32 string indicating a wtid
- * @param exchange base URL of the exchange in charge of returning the wanted 
information
- * @param track_transfer_cb the callback to call when a reply for this request 
is available
- * @param track_transfer_cb_cls closure for @a track_transfer_cb
+ * @param payto_uri which account was credited by the wire transfer
+ * @param exchange_url what is the URL of the exchange that made the transfer
+ * @param cb the callback to call when a reply for this request is available
+ * @param cb_cls closure for @a cb
  * @return a handle for this request
  */
-struct TALER_MERCHANT_TrackTransferHandle *
-TALER_MERCHANT_track_transfer (
+struct TALER_MERCHANT_PostTransfersHandle *
+TALER_MERCHANT_transfers_post (
   struct GNUNET_CURL_Context *ctx,
   const char *backend_url,
-  const char *wire_method,
+  const struct TALER_Amount *credit_amount,
   const struct TALER_WireTransferIdentifierRawP *wtid,
+  const char *payto_uri,
   const char *exchange_url,
-  TALER_MERCHANT_TrackTransferCallback
-  track_transfer_cb,
-  void *track_transfer_cb_cls);
+  TALER_MERCHANT_TrackTransferCallback cb,
+  void *cls);
 
 
 /**
- * Cancel a /track/transfer request.  This function cannot be used
+ * Cancel a POST /transfers request.  This function cannot be used
  * on a request handle if a response is already served for it.
  *
- * @param co the deposit's tracking operation
+ * @param pth the operation to cancel
  */
 void
-TALER_MERCHANT_track_transfer_cancel (
-  struct TALER_MERCHANT_TrackTransferHandle *tdo);
-
+TALER_MERCHANT_transfers_post_cancel (
+  struct TALER_MERCHANT_PostTransfersHandle *pth);
 
-/* ********************* /track/transaction *********************** */
 
 /**
- * @brief Handle to a /track/transaction operation at a merchant's backend.
+ * @brief Handle to a GET /transfers operation at a merchant's backend.
  */
-struct TALER_MERCHANT_TrackTransactionHandle;
+struct TALER_MERCHANT_GetTransfersHandle;
 
 /**
- * Information about a coin aggregated in a wire transfer for a
- * /track/transaction response.
+ * Information about the _total_ amount that was paid back
+ * by the exchange for a given h_contract_terms, by _one_ wire
+ * transfer.
  */
-struct TALER_MERCHANT_CoinWireTransfer
+struct TALER_MERCHANT_TransferData
 {
 
   /**
-   * Public key of the coin.
+   * Total amount wired by the exchange (without wire fee)
    */
-  struct TALER_CoinSpendPublicKeyP coin_pub;
+  struct TALER_Amount credit_amount;
 
   /**
-   * Value of the coin including deposit fee.
+   * Wire transfer identifier used.
    */
-  struct TALER_Amount amount_with_fee;
+  struct TALER_WireTransferIdentifierRawP wtid;
 
   /**
-   * Deposit fee for the coin.
+   * URI of the target account.
    */
-  struct TALER_Amount deposit_fee;
+  const char *payto_uri;
 
-};
+  /**
+   * URL of the exchange that made the transfer.
+   */
+  const char *exchange_url;
 
+  /**
+   * Serial number of the credit operation in the merchant backend.
+   */
+  uint64_t credit_serial;
+
+  /**
+   * Time of the wire transfer, according to the exchange.
+   */
+  struct GNUNET_TIME_Absolute execution_time;
+
+  /**
+   * Did we check the exchange's answer and are happy about it?  False
+   * if we did not check or are unhappy with the answer.
+   */
+  bool verified;
+
+  /**
+   * Did we confirm the wire transfer happened (via 
#TALER_MERCHANT_transfers_post())?
+   */
+  bool confirmed;
+
+};
 
 /**
  * Callbacks of this type are used to work the result of submitting a
- * /track/transaction request to a merchant
+ * GET /transfers request to a merchant
  *
  * @param cls closure
- * @param http_status HTTP status code we got, 0 on exchange protocol violation
- * @param ec taler-specific error code
- * @param json original json reply from the backend
- * @param num_transfers number of wire transfers the exchange used for the 
transaction
- * @param transfers details about each transfer and which coins are aggregated 
in it
-*/
+ * @param hr HTTP response details
+ * @param transfers_length length of the @a transfers array
+ * @param transfers array with details about the transfers we received
+ */
 typedef void
-(*TALER_MERCHANT_TrackTransactionCallback) (
+(*TALER_MERCHANT_GetTransfersCallback) (
   void *cls,
-  const struct TALER_MERCHANT_HttpResponse *hr);
+  const struct TALER_MERCHANT_HttpResponse *hr,
+  unsigned int transfers_length,
+  const struct TALER_MERCHANT_TransferData transfers[]);
 
 
 /**
- * Request backend to return deposits associated with a given wtid.
+ * Request backend to return list of all wire transfers that
+ * we received (or that the exchange claims we should have received).
+ *
+ * Note that when filtering by timestamp (using “before” and/or “after”), we
+ * use the time reported by the exchange and thus will ONLY return results for
+ * which we already have a response from the exchange. This should be
+ * virtually all transfers, however it is conceivable that for some transfer
+ * the exchange responded with a temporary error (i.e. HTTP status 500+) and
+ * then we do not yet have an execution time to filter by. Thus, IF timestamp
+ * filters are given, transfers for which we have no response from the
+ * exchange yet are automatically excluded.
  *
  * @param ctx execution context
  * @param backend_url base URL of the backend
- * @param order_id which order should we trace
- * @param track_transaction_cb the callback to call when a reply for this 
request is available
- * @param track_transaction_cb_cls closure for @a track_transaction_cb
+ * @param payto_uri filter by this credit account of the merchant
+ * @param before limit to transactions before this timestamp, use
+ *                 #GNUNET_TIME_UNIT_FOREVER_ABS to not filter by @a before
+ * @param after limit to transactions after this timestamp, use
+ *                 #GNUNET_TIME_UNIT_ZERO_ABS to not filter by @a after
+ * @param limit return at most ths number of results; negative to descend in 
execution time
+ * @param offset start at this "credit serial" number (exclusive)
+ * @param verified filter results by verification status
+ * @param cb the callback to call when a reply for this request is available
+ * @param cb_cls closure for @a cb
  * @return a handle for this request
  */
-struct TALER_MERCHANT_TrackTransactionHandle *
-TALER_MERCHANT_track_transaction (
+struct TALER_MERCHANT_GetTransfersHandle *
+TALER_MERCHANT_transfers_post (
   struct GNUNET_CURL_Context *ctx,
   const char *backend_url,
-  const char *order_id,
-  TALER_MERCHANT_TrackTransactionCallback track_transaction_cb,
-  void *track_transaction_cb_cls);
+  const char *payto_uri,
+  const struct GNUNET_TIME_Absolute before,
+  const struct GNUNET_TIME_Absolute after,
+  int64_t limit,
+  uint64_t offset,
+  enum TALER_MERCHANT_YesNoAll verified,
+  TALER_MERCHANT_GetTransfersCallback cb,
+  void *cls);
 
 
 /**
- * Cancel a /track/transaction request.  This function cannot be used
+ * Cancel a POST /transfers request.  This function cannot be used
  * on a request handle if a response is already served for it.
  *
- * @param tdo the tracking request to cancel
+ * @param pth the operation to cancel
  */
 void
-TALER_MERCHANT_track_transaction_cancel (
-  struct TALER_MERCHANT_TrackTransactionHandle *tdo);
+TALER_MERCHANT_transfers_get_cancel (
+  struct TALER_MERCHANT_GetTransfersHandle *gth);
+
+
+/* *********************   OLD ************************** */
 
 
 /* ********************** /tip-authorize ********************** */
@@ -2519,9 +2573,6 @@ TALER_MERCHANT_tip_pickup2_cancel (
   struct TALER_MERCHANT_TipPickup2Operation *tp);
 
 
-/* ********************** /check-payment ************************* */
-
-
 /* ********************** /tip-query ************************* */
 
 /**
@@ -2585,4 +2636,83 @@ void
 TALER_MERCHANT_tip_query_cancel (struct TALER_MERCHANT_TipQueryOperation *tqh);
 
 
+/* ********************* /track/transaction (UNSPEC!) *********************** 
*/
+
+/**
+ * @brief Handle to a /track/transaction operation at a merchant's backend.
+ */
+struct TALER_MERCHANT_TrackTransactionHandle;
+
+/**
+ * Information about a coin aggregated in a wire transfer for a
+ * /track/transaction response.
+ */
+struct TALER_MERCHANT_CoinWireTransfer
+{
+
+  /**
+   * Public key of the coin.
+   */
+  struct TALER_CoinSpendPublicKeyP coin_pub;
+
+  /**
+   * Value of the coin including deposit fee.
+   */
+  struct TALER_Amount amount_with_fee;
+
+  /**
+   * Deposit fee for the coin.
+   */
+  struct TALER_Amount deposit_fee;
+
+};
+
+
+/**
+ * Callbacks of this type are used to work the result of submitting a
+ * /track/transaction request to a merchant
+ *
+ * @param cls closure
+ * @param http_status HTTP status code we got, 0 on exchange protocol violation
+ * @param ec taler-specific error code
+ * @param json original json reply from the backend
+ * @param num_transfers number of wire transfers the exchange used for the 
transaction
+ * @param transfers details about each transfer and which coins are aggregated 
in it
+*/
+typedef void
+(*TALER_MERCHANT_TrackTransactionCallback) (
+  void *cls,
+  const struct TALER_MERCHANT_HttpResponse *hr);
+
+
+/**
+ * Request backend to return deposits associated with a given wtid.
+ *
+ * @param ctx execution context
+ * @param backend_url base URL of the backend
+ * @param order_id which order should we trace
+ * @param track_transaction_cb the callback to call when a reply for this 
request is available
+ * @param track_transaction_cb_cls closure for @a track_transaction_cb
+ * @return a handle for this request
+ */
+struct TALER_MERCHANT_TrackTransactionHandle *
+TALER_MERCHANT_track_transaction (
+  struct GNUNET_CURL_Context *ctx,
+  const char *backend_url,
+  const char *order_id,
+  TALER_MERCHANT_TrackTransactionCallback track_transaction_cb,
+  void *track_transaction_cb_cls);
+
+
+/**
+ * Cancel a /track/transaction request.  This function cannot be used
+ * on a request handle if a response is already served for it.
+ *
+ * @param tdo the tracking request to cancel
+ */
+void
+TALER_MERCHANT_track_transaction_cancel (
+  struct TALER_MERCHANT_TrackTransactionHandle *tdo);
+
+
 #endif  /* _TALER_MERCHANT_SERVICE_H */

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.