Fix wallet API docs and adjust withdraw API

1 files changed, 104 insertions, 79 deletions

diff --git a/taler-wallet.rst b/taler-wallet.rst
index 6dd37749..604203b1 100644
--- a/taler-wallet.rst
+++ b/taler-wallet.rst
@@ -219,6 +219,8 @@ Transactions are all operations or events that are affecting the balance.
       | WithdrawalDetailsForManualTransfer
       | WithdrawalDetailsForTalerBankIntegrationApi;
 
+  .. ts:def:: WithdrawalDetailsForManualTransfer
+
     interface WithdrawalDetailsForManualTransfer {
       type: "manual-transfer";
 
@@ -227,6 +229,8 @@ Transactions are all operations or events that are affecting the balance.
       exchangePaytoUris: string[];
     }
 
+  .. ts:def:: WithdrawalDetailsForTalerBankIntegrationApi
+
     interface WithdrawalDetailsForTalerBankIntegrationApi {
       type: "taler-bank-integration-api";
 
@@ -420,8 +424,11 @@ Refunds
       contractTermsHash: string;
     }
 
-Exchange Management: List Exchanges
------------------------------------
+Exchange Management
+-------------------
+
+List Exchanges
+~~~~~~~~~~~~~~
 
 :Name: ``"listExchanges"``
 :Description:
@@ -429,9 +436,9 @@ Exchange Management: List Exchanges
 :CLI:
   ``taler-wallet-cli exchanges list``
 :Response:
-  .. ts:def:: ExchangesListRespose
+  .. ts:def:: ExchangesListResponse
   
-    interface ExchangesListRespose {
+    interface ExchangesListResponse {
       exchanges: ExchangeListItem[];
     }
 
@@ -443,8 +450,8 @@ Exchange Management: List Exchanges
       paytoUris: string[];
     }
 
-Exchange Management: Add Exchange
----------------------------------
+Add Exchange
+~~~~~~~~~~~~
 
 :Name: ``"addExchange"``
 :Description:
@@ -458,10 +465,34 @@ Exchange Management: Add Exchange
       exchangeBaseUrl: string;
     }
 :Response:
-  On success, the response is an empty object.
+  On success, the response is an `ExchangeListItem`.
+
+
+Get Suggested Exchanges
+~~~~~~~~~~~~~~~~~~~~~~~
+
+:Name: ``"getSuggestedExchanges"``
+:Description:
+  Get default exchange and the bank's suggested exchange for a given withdrawal URI.
+:Request:
+  .. ts:def:: ExchangeGetSuggestedRequest
+
+    interface ExchangeGetSuggestedRequest {
+      talerWithdrawUri: string;
+    }
+:Response:
+  .. ts:def:: ExchangeGetSuggestedResponse
+
+    interface ExchangeGetSuggestedResponse {
+      // Exchange suggested by the wallet
+      defaultExchange?: string;
 
-Exchange Management: Get Terms of Service
------------------------------------------
+      // Exchange suggested by the bank
+      bankSuggestedExchange?: string;
+    }
+
+Get Terms of Service
+~~~~~~~~~~~~~~~~~~~~
 
 :Name: ``"getExchangeTos"``
 :Description:
@@ -478,7 +509,7 @@ Exchange Management: Get Terms of Service
 :Response:
   .. ts:def:: ExchangeGetTosResult
 
-    export interface GetExchangeTosResult {
+    interface GetExchangeTosResult {
       // Markdown version of the current ToS.
       tos: string;
 
@@ -490,8 +521,8 @@ Exchange Management: Get Terms of Service
       acceptedEtag: string | undefined;
     }
 
-Exchange Management: Set Accepted Terms of Service Version
-----------------------------------------------------------
+Set Accepted Terms of Service Version
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 :Name: ``"setExchangeTosAccepted"``
 :Description:
@@ -509,8 +540,11 @@ Exchange Management: Set Accepted Terms of Service Version
   On success, the response is an empty object.
 
 
-Withdrawal: Withdraw balance from test environment
---------------------------------------------------
+Withdrawal
+----------
+
+Withdraw balance from test environment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 :Name: ``"withdrawTestkudos"``
 :Description:
@@ -523,93 +557,57 @@ Withdrawal: Withdraw balance from test environment
   On success, the response is an empty object.
 
 
-Withdrawal: Get Manual Withdrawal Info
---------------------------------------
+Get Withdrawal Info For Bank-integrated Withdrawal
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-:Name: ``"getWithdrawalDetailsForAmount"``
+:Name: ``"getWithdrawalDetailsForUri"``
 :Description:
-  Get information about fees and exchange for a manual withdrawal of a given amount.
-:CLI:
-  ``taler-wallet-cli advanced manual-withdrawal-details $URL $AMOUNT``
+  Get information about fees for a bank-integrated withdrawal from a taler://withdraw URI.
 :Request:
   .. ts:def:: GetManualWithdrawalDetailsRequest
 
-    interface ExchangeAddRequest {
+    interface GetManualWithdrawalDetailsRequest {
+      talerWithdrawUri: string;
       exchangeBaseUrl: string;
-      amount: string;
     }
 :Response:
-  .. ts:def:: ManualWithdrawalDetails
+  .. ts:def:: WithdrawalDetailsForUri
 
-    export interface ManualWithdrawalDetails {
+    interface WithdrawalDetailsForUri {
       // Did the user accept the current version of the exchange's
       // terms of service?
       tosAccepted: boolean;
 
-      // Amount that the user will transfer to the exchange.
-      rawAmount: AmountString;
+      // Amount that the bank will transfer to the exchange.
+      rawAmount: Amount;
 
       // Amount that will be added to the user's wallet balance.
-      effectiveAmount: AmountString;
-
-      // Ways to pay the exchange.
-      paytoUris: string[];
+      effectiveAmount: Amount;
     }
 
-Withdrawal: Get Withdrawal Info For Bank-integrated Withdrawal
---------------------------------------------------------------
+Accept Bank-integrated Withdrawal
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-:Name: ``"getWithdrawalDetailsForUri"``
+:Name: ``"acceptWithdrawal"``
 :Description:
-  Get information about fees and exchange for a bank-integrated withdrawal
-  from a taler://withdraw URI.
+  Accept a bank-integrated withdrawal, where the bank transfers funds automatically.
 :Request:
   .. ts:def:: GetManualWithdrawalDetailsRequest
 
-    interface ExchangeAddRequest {
+    interface AcceptWithdrawalRequest {
       talerWithdrawUri: string;
-      // Selected exchange, if an exchange has been selected already
-      // by the user (or preselected by the wallet)
-      selectedExchange?: string;
-    }
-:Response:
-  .. ts:def:: WithdrawalDetailsForUri
-
-    export interface WithdrawalDetailsForUri {
-      // Did the user accept the current version of the exchange's
-      // terms of service?
-      tosAccepted: boolean;
-
-      // Exchange suggested by the bank
-      bankSuggestedExchange?: string;
-    }
-
-Withdrawal: Accept Manual Withdrawal
-------------------------------------
-
-:Name: ``"acceptManualWithdrawal"``
-:Description:
-  Accept a manual withdrawal, where the user has to transfer funds manually.
-:CLI:
-  ``taler-wallet-cli advanced withdraw-manually --exchange $EXCHANGE --amount $AMOUNT``
-:Request:
-  .. ts:def:: AcceptManualWithdrawalRequest
-
-    interface AcceptManualWithdrawalRequest {
       exchangeBaseUrl: string;
-      amount: AmountString;
     }
 :Response:
-  .. ts:def:: AcceptManualWithdrawalResponse
+  .. ts:def:: AcceptWithdrawalResponse
 
-    interface AcceptManualWithdrawalResponse {
-      // Payto URIs to fund the withdrawal,
-      // with amount and message provided.
-      exchangePaytoUris: string[];
+    interface AcceptWithdrawalResponse {
+      // a URL for user initiated confirmation.
+      bankConfirmationUrl?: string;
     }
 
-Withdrawal: Get Manual Withdrawal Info
---------------------------------------
+Get Manual Withdrawal Info
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 :Name: ``"getWithdrawalDetailsForAmount"``
 :Description:
@@ -626,16 +624,16 @@ Withdrawal: Get Manual Withdrawal Info
 :Response:
   .. ts:def:: ManualWithdrawalDetails
 
-    export interface ManualWithdrawalDetails {
+    interface ManualWithdrawalDetails {
       // Did the user accept the current version of the exchange's
       // terms of service?
       tosAccepted: boolean;
 
       // Amount that the user will transfer to the exchange.
-      rawAmount: AmountString;
+      rawAmount: Amount;
 
       // Amount that will be added to the user's wallet balance.
-      effectiveAmount: AmountString;
+      effectiveAmount: Amount;
 
       // Ways to pay the exchange.
       // Does not include the amount and message, as the
@@ -643,15 +641,42 @@ Withdrawal: Get Manual Withdrawal Info
       paytoUris: string[];
     }
 
-Payments: Prepare Pay
----------------------
+Accept Manual Withdrawal
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+:Name: ``"acceptManualWithdrawal"``
+:Description:
+  Accept a manual withdrawal, where the user has to transfer funds manually.
+:CLI:
+  ``taler-wallet-cli advanced withdraw-manually --exchange $EXCHANGE --amount $AMOUNT``
+:Request:
+  .. ts:def:: AcceptManualWithdrawalRequest
+
+    interface AcceptManualWithdrawalRequest {
+      exchangeBaseUrl: string;
+      amount: Amount;
+    }
+:Response:
+  .. ts:def:: AcceptManualWithdrawalResponse
+
+    interface AcceptManualWithdrawalResponse {
+      // Payto URIs to fund the withdrawal,
+      // with amount and message provided.
+      exchangePaytoUris: string[];
+    }
+
+Payments
+--------
+
+Prepare Pay
+~~~~~~~~~~~
 
 :Name: ``"preparePay"``
 :Description:
   Fetch information about a payment request from a merchant.
 
-Payments: Confirm Payment
--------------------------
+Confirm Payment
+~~~~~~~~~~~~~~~
 
 :Name: ``"confirmPay"``
 :Description: