update wallet-core docs

1 files changed, 276 insertions, 91 deletions

diff --git a/wallet/wallet-core.md b/wallet/wallet-core.md
index 5575a251..f860cfbd 100644
--- a/wallet/wallet-core.md
+++ b/wallet/wallet-core.md
@@ -7,14 +7,21 @@ This file is auto-generated from [wallet-core](https://git.taler.net/wallet-core
 ###  Basic Wallet Information
 * [GetBalancesOp](#getbalancesop)
 * [GetBalancesDetailOp](#getbalancesdetailop)
+* [GetPlanForOperationOp](#getplanforoperationop)
+* [ConvertDepositAmountOp](#convertdepositamountop)
+* [GetMaxDepositAmountOp](#getmaxdepositamountop)
+* [ConvertPeerPushAmountOp](#convertpeerpushamountop)
+* [GetMaxPeerPushAmountOp](#getmaxpeerpushamountop)
+* [ConvertWithdrawalAmountOp](#convertwithdrawalamountop)
 ###  Managing Transactions
 * [GetTransactionsOp](#gettransactionsop)
+* [TestingGetSampleTransactionsOp](#testinggetsampletransactionsop)
 * [GetTransactionByIdOp](#gettransactionbyidop)
 * [RetryPendingNowOp](#retrypendingnowop)
 * [DeleteTransactionOp](#deletetransactionop)
 * [RetryTransactionOp](#retrytransactionop)
 * [AbortTransactionOp](#aborttransactionop)
-* [CancelAbortingTransactionOp](#cancelabortingtransactionop)
+* [FailTransactionOp](#failtransactionop)
 * [SuspendTransactionOp](#suspendtransactionop)
 * [ResumeTransactionOp](#resumetransactionop)
 ###  Withdrawals
@@ -237,6 +244,122 @@ export interface AmountJson {
 
 ```
 
+### GetPlanForOperationOp
+```typescript
+export type GetPlanForOperationOp = {
+  op: WalletApiOperation.GetPlanForOperation;
+  request: GetPlanForOperationRequest;
+  response: GetPlanForOperationResponse;
+};
+// GetPlanForOperation = "getPlanForOperation"
+
+```
+```typescript
+export type GetPlanForOperationRequest =
+  | GetPlanForWithdrawRequest
+  | GetPlanForDepositRequest;
+
+```
+```typescript
+interface GetPlanForWithdrawRequest extends GetPlanForWalletInitiatedOperation {
+  type: TransactionType.Withdrawal;
+  exchangeUrl?: string;
+}
+
+```
+```typescript
+interface GetPlanForWalletInitiatedOperation {
+  instructedAmount: AmountString;
+  mode: TransactionAmountMode;
+}
+
+```
+```typescript
+/**
+ * How the amount should be interpreted in a transaction
+ * Effective = how the balance is change
+ * Raw = effective amount without fee
+ *
+ * Depending on the transaction, raw can be higher than effective
+ */
+export declare enum TransactionAmountMode {
+  Effective = "effective",
+  Raw = "raw",
+}
+
+```
+```typescript
+interface GetPlanForDepositRequest extends GetPlanForWalletInitiatedOperation {
+  type: TransactionType.Deposit;
+  account: string;
+}
+
+```
+```typescript
+export interface GetPlanForOperationResponse {
+  effectiveAmount: AmountString;
+  rawAmount: AmountString;
+  counterPartyAmount?: AmountString;
+  details: any;
+}
+
+```
+
+### ConvertDepositAmountOp
+```typescript
+export type ConvertDepositAmountOp = {
+  op: WalletApiOperation.ConvertDepositAmount;
+  request: ConvertAmountRequest;
+  response: AmountResponse;
+};
+// ConvertDepositAmount = "ConvertDepositAmount"
+
+```
+
+### GetMaxDepositAmountOp
+```typescript
+export type GetMaxDepositAmountOp = {
+  op: WalletApiOperation.GetMaxDepositAmount;
+  request: GetAmountRequest;
+  response: AmountResponse;
+};
+// GetMaxDepositAmount = "GetMaxDepositAmount"
+
+```
+
+### ConvertPeerPushAmountOp
+```typescript
+export type ConvertPeerPushAmountOp = {
+  op: WalletApiOperation.ConvertPeerPushAmount;
+  request: ConvertAmountRequest;
+  response: AmountResponse;
+};
+// ConvertPeerPushAmount = "ConvertPeerPushAmount"
+
+```
+
+### GetMaxPeerPushAmountOp
+```typescript
+export type GetMaxPeerPushAmountOp = {
+  op: WalletApiOperation.GetMaxPeerPushAmount;
+  request: GetAmountRequest;
+  response: AmountResponse;
+};
+// GetMaxPeerPushAmount = "GetMaxPeerPushAmount"
+
+```
+
+### ConvertWithdrawalAmountOp
+```typescript
+export type ConvertWithdrawalAmountOp = {
+  op: WalletApiOperation.ConvertWithdrawalAmount;
+  request: ConvertAmountRequest;
+  response: AmountResponse;
+};
+// ConvertWithdrawalAmount = "ConvertWithdrawalAmount"
+
+```
+
 ### GetTransactionsOp
 ```typescript
 /**
@@ -267,10 +390,18 @@ export interface TransactionsRequest {
 }
 
 ```
+
+### TestingGetSampleTransactionsOp
 ```typescript
-export interface TransactionsResponse {
-  transactions: Transaction[];
-}
+/**
+ * Get sample transactions.
+ */
+export type TestingGetSampleTransactionsOp = {
+  op: WalletApiOperation.TestingGetSampleTransactions;
+  request: EmptyObject;
+  response: TransactionsResponse;
+};
+// TestingGetSampleTransactions = "testingGetSampleTransactions"
 
 ```
 
@@ -317,7 +448,7 @@ export type DeleteTransactionOp = {
 ```
 ```typescript
 export interface DeleteTransactionRequest {
-  transactionId: string;
+  transactionId: TransactionIdStr;
 }
 
 ```
@@ -337,7 +468,7 @@ export type RetryTransactionOp = {
 ```
 ```typescript
 export interface RetryTransactionRequest {
-  transactionId: string;
+  transactionId: TransactionIdStr;
 }
 
 ```
@@ -358,24 +489,24 @@ export type AbortTransactionOp = {
 
 ```
 
-### CancelAbortingTransactionOp
+### FailTransactionOp
 ```typescript
 /**
  * Cancel aborting a transaction
  *
  * For payment transactions, it puts the payment into an "aborting" state.
  */
-export type CancelAbortingTransactionOp = {
-  op: WalletApiOperation.CancelAbortingTransaction;
-  request: CancelAbortingTransactionRequest;
+export type FailTransactionOp = {
+  op: WalletApiOperation.FailTransaction;
+  request: FailTransactionRequest;
   response: EmptyObject;
 };
-// CancelAbortingTransaction = "cancelAbortingTransaction"
+// FailTransaction = "failTransaction"
 
 ```
 ```typescript
-export interface CancelAbortingTransactionRequest {
-  transactionId: string;
+export interface FailTransactionRequest {
+  transactionId: TransactionIdStr;
 }
 
 ```
@@ -445,6 +576,12 @@ export interface ManualWithdrawalDetails {
    */
   amountEffective: AmountString;
   /**
+   * Number of coins that would be used for withdrawal.
+   *
+   * The UIs should warn if this number is too high (roughly at >100).
+   */
+  numCoins: number;
+  /**
    * Ways to pay the exchange.
    */
   paytoUris: string[];
@@ -512,7 +649,7 @@ export interface AcceptBankIntegratedWithdrawalRequest {
 export interface AcceptWithdrawalResponse {
   reservePub: string;
   confirmTransferUrl?: string;
-  transactionId: string;
+  transactionId: TransactionIdStr;
 }
 
 ```
@@ -548,7 +685,7 @@ export interface AcceptManualWithdrawalResult {
    * Public key of the newly created reserve.
    */
   reservePub: string;
-  transactionId: string;
+  transactionId: TransactionIdStr;
 }
 
 ```
@@ -695,14 +832,14 @@ export type ConfirmPayResult = ConfirmPayResultDone | ConfirmPayResultPending;
 export interface ConfirmPayResultDone {
   type: ConfirmPayResultType.Done;
   contractTerms: MerchantContractTerms;
-  transactionId: string;
+  transactionId: TransactionIdStr;
 }
 
 ```
 ```typescript
 export interface ConfirmPayResultPending {
   type: ConfirmPayResultType.Pending;
-  transactionId: string;
+  transactionId: TransactionIdStr;
   lastError: TalerErrorDetail | undefined;
 }
 
@@ -729,7 +866,7 @@ export interface PrepareRefundRequest {
 ```
 ```typescript
 export interface StartRefundQueryForUriResponse {
-  transactionId: string;
+  transactionId: TransactionIdStr;
 }
 
 ```
@@ -746,7 +883,7 @@ export type StartRefundQueryOp = {
 ```
 ```typescript
 export interface StartRefundQueryRequest {
-  transactionId: string;
+  transactionId: TransactionIdStr;
 }
 
 ```
@@ -775,9 +912,15 @@ export interface PrepareTipResult {
   /**
    * Unique ID for the tip assigned by the wallet.
    * Typically different from the merchant-generated tip ID.
+   *
+   * @deprecated use transactionId instead
    */
   walletTipId: string;
   /**
+   * Tip transaction ID.
+   */
+  transactionId: string;
+  /**
    * Has the tip already been accepted?
    */
   accepted: boolean;
@@ -829,7 +972,7 @@ export interface AcceptTipRequest {
 ```
 ```typescript
 export interface AcceptTipResponse {
-  transactionId: string;
+  transactionId: TransactionIdStr;
   next_url?: string;
 }
 
@@ -1169,7 +1312,7 @@ export type GenerateDepositGroupTxIdOp = {
 ```
 ```typescript
 export interface TxIdResponse {
-  transactionId: string;
+  transactionId: TransactionIdStr;
 }
 
 ```
@@ -1207,7 +1350,7 @@ export interface CreateDepositGroupRequest {
 ```typescript
 export interface CreateDepositGroupResponse {
   depositGroupId: string;
-  transactionId: string;
+  transactionId: TransactionIdStr;
 }
 
 ```
@@ -1433,8 +1576,8 @@ export interface ProviderInfo {
    * Last communication issue with the provider.
    */
   lastError?: TalerErrorDetail;
-  lastSuccessfulBackupTimestamp?: TalerProtocolTimestamp;
-  lastAttemptedBackupTimestamp?: TalerProtocolTimestamp;
+  lastSuccessfulBackupTimestamp?: TalerPreciseTimestamp;
+  lastAttemptedBackupTimestamp?: TalerPreciseTimestamp;
   paymentProposalIds: string[];
   backupProblem?: BackupProblem;
   paymentStatus: ProviderPaymentStatus;
@@ -1619,7 +1762,7 @@ export interface InitiatePeerPushDebitResponse {
   mergePriv: string;
   contractPriv: string;
   talerUri: string;
-  transactionId: string;
+  transactionId: TransactionIdStr;
 }
 
 ```
@@ -1631,7 +1774,7 @@ export interface InitiatePeerPushDebitResponse {
  */
 export type PreparePeerPushCreditOp = {
   op: WalletApiOperation.PreparePeerPushCredit;
-  request: PreparePeerPushCredit;
+  request: PreparePeerPushCreditRequest;
   response: PreparePeerPushCreditResponse;
 };
 // PreparePeerPushCredit = "preparePeerPushCredit"
@@ -1647,6 +1790,7 @@ export interface PreparePeerPushCreditResponse {
   amountRaw: AmountString;
   amountEffective: AmountString;
   peerPushPaymentIncomingId: string;
+  transactionId: string;
 }
 
 ```
@@ -1730,7 +1874,7 @@ export interface InitiatePeerPullCreditResponse {
    * that was requested.
    */
   talerUri: string;
-  transactionId: string;
+  transactionId: TransactionIdStr;
 }
 
 ```
@@ -1764,6 +1908,7 @@ export interface PreparePeerPullDebitResponse {
   amountRaw: AmountString;
   amountEffective: AmountString;
   peerPullPaymentIncomingId: string;
+  transactionId: string;
 }
 
 ```
@@ -2118,7 +2263,7 @@ export interface PendingTaskInfoCommon {
   /**
    * Unique identifier for the pending task.
    */
-  id: string;
+  id: TaskId;
   /**
    * Set to true if the operation indicates that something is really in progress,
    * as opposed to some regular scheduled operation that can be tried later.
@@ -2163,6 +2308,12 @@ export enum PendingTaskType {
 
 ```
 ```typescript
+export type TaskId = string & {
+  [__taskId]: true;
+};
+
+```
+```typescript
 export interface RetryInfo {
   firstTry: AbsoluteTime;
   nextRetry: AbsoluteTime;
@@ -2614,6 +2765,11 @@ export interface WalletCoreVersion {
 }
 ```
 ```typescript
+export interface TransactionsResponse {
+  transactions: Transaction[];
+}
+```
+```typescript
 export type Transaction =
   | TransactionWithdrawal
   | TransactionPayment
@@ -2624,9 +2780,13 @@ export type Transaction =
   | TransactionPeerPullCredit
   | TransactionPeerPullDebit
   | TransactionPeerPushCredit
-  | TransactionPeerPushDebit;
+  | TransactionPeerPushDebit
+  | TransactionInternalWithdrawal;
 ```
 ```typescript
+/**
+ * A withdrawal transaction (either bank-integrated or manual).
+ */
 export interface TransactionWithdrawal extends TransactionCommon {
   type: TransactionType.Withdrawal;
   /**
@@ -2648,30 +2808,15 @@ export interface TransactionWithdrawal extends TransactionCommon {
 export interface TransactionCommon {
   transactionId: TransactionIdStr;
   type: TransactionType;
-  timestamp: TalerProtocolTimestamp;
+  timestamp: TalerPreciseTimestamp;
   /**
    * Transaction state, as per DD37.
    */
   txState: TransactionState;
   /**
-   * @deprecated in favor of statusMajor and statusMinor
-   */
-  extendedStatus: ExtendedStatus;
-  /**
-   * true if the transaction is still pending, false otherwise
-   * If a transaction is not longer pending, its timestamp will be updated,
-   * but its transactionId will remain unchanged
-   *
-   * @deprecated show extendedStatus
-   */
-  pending: boolean;
-  /**
-   * True if the transaction encountered a problem that might be
-   * permanent.  A frozen transaction won't be automatically retried.
-   *
-   * @deprecated show extendedStatus
+   * Possible transitions based on the current state.
    */
-  frozen: boolean;
+  txActions: string[];
   /**
    * Raw amount of the transaction (exclusive of fees or other extra costs).
    */
@@ -2681,11 +2826,22 @@ export interface TransactionCommon {
    */
   amountEffective: AmountString;
   error?: TalerErrorDetail;
+  /**
+   * If the transaction minor state is in KycRequired this field is going to
+   * have the location where the user need to go to complete KYC information.
+   */
+  kycUrl?: string;
 }
 ```
 ```typescript
+export type TransactionIdStr = `txn:${string}:${string}` & {
+  [__txId]: true;
+};
+```
+```typescript
 export declare enum TransactionType {
   Withdrawal = "withdrawal",
+  InternalWithdrawal = "internal-withdrawal",
   Payment = "payment",
   Refund = "refund",
   Refresh = "refresh",
@@ -2698,8 +2854,25 @@ export declare enum TransactionType {
 }
 ```
 ```typescript
+export interface TalerPreciseTimestamp {
+  /**
+   * Seconds (as integer) since epoch.
+   */
+  readonly t_s: number | "never";
+  /**
+   * Optional microsecond offset (non-negative integer).
+   */
+  readonly off_us?: number;
+  readonly _flavor?: typeof flavor_TalerPreciseTimestamp;
+}
+```
+```typescript
 export interface TalerProtocolTimestamp {
+  /**
+   * Seconds (as integer) since epoch.
+   */
   readonly t_s: number | "never";
+  readonly _flavor?: typeof flavor_TalerProtocolTimestamp;
 }
 ```
 ```typescript
@@ -2719,8 +2892,8 @@ export declare enum TransactionMajorState {
   Dialog = "dialog",
   SuspendedAborting = "suspended-aborting",
   Failed = "failed",
+  Expired = "expired",
   Deleted = "deleted",
-  Unknown = "unknown",
 }
 ```
 ```typescript
@@ -2731,7 +2904,7 @@ export declare enum TransactionMinorState {
   AmlRequired = "aml",
   MergeKycRequired = "merge-kyc",
   Track = "track",
-  Pay = "pay",
+  SubmitPayment = "submit-payment",
   RebindSession = "rebind-session",
   Refresh = "refresh",
   Pickup = "pickup",
@@ -2751,6 +2924,7 @@ export declare enum TransactionMinorState {
   WithdrawCoins = "withdraw-coins",
   ExchangeWaitReserve = "exchange-wait-reserve",
   AbortingBank = "aborting-bank",
+  Aborting = "aborting",
   Refused = "refused",
   Withdraw = "withdraw",
   MerchantOrderProposed = "merchant-order-proposed",
@@ -2760,16 +2934,6 @@ export declare enum TransactionMinorState {
 }
 ```
 ```typescript
-export declare enum ExtendedStatus {
-  Pending = "pending",
-  Done = "done",
-  Aborting = "aborting",
-  Aborted = "aborted",
-  Failed = "failed",
-  KycRequired = "kyc-required",
-}
-```
-```typescript
 export interface TalerErrorDetail {
   code: TalerErrorCode;
   when?: AbsoluteTime;
@@ -2783,6 +2947,8 @@ export interface AbsoluteTime {
    * Timestamp in milliseconds.
    */
   readonly t_ms: number | "never";
+  readonly _flavor?: typeof flavor_AbsoluteTime;
+  [opaque_AbsoluteTime]: true;
 }
 ```
 ```typescript
@@ -2852,12 +3018,6 @@ export interface TransactionPayment extends TransactionCommon {
    */
   proposalId: string;
   /**
-   * How far did the wallet get with processing the payment?
-   *
-   * @deprecated use extendedStatus
-   */
-  status: PaymentStatus;
-  /**
    * Amount that must be paid for the contract
    */
   amountRaw: AmountString;
@@ -2992,27 +3152,6 @@ export interface Tax {
 }
 ```
 ```typescript
-export declare enum PaymentStatus {
-  /**
-   * Explicitly aborted after timeout / failure
-   */
-  Aborted = "aborted",
-  /**
-   * Payment failed, wallet will auto-retry.
-   * User should be given the option to retry now / abort.
-   */
-  Failed = "failed",
-  /**
-   * Paid successfully
-   */
-  Paid = "paid",
-  /**
-   * User accepted, payment is processing.
-   */
-  Accepted = "accepted",
-}
-```
-```typescript
 export interface RefundInfoShort {
   transactionId: string;
   timestamp: TalerProtocolTimestamp;
@@ -3023,9 +3162,23 @@ export interface RefundInfoShort {
 ```typescript
 export interface TransactionRefund extends TransactionCommon {
   type: TransactionType.Refund;
-  refundedTransactionId: string;
   amountRaw: AmountString;
   amountEffective: AmountString;
+  refundedTransactionId: string;
+  paymentInfo: RefundPaymentInfo | undefined;
+}
+```
+```typescript
+/**
+ * Summary information about the payment that we got a refund for.
+ */
+export interface RefundPaymentInfo {
+  summary: string;
+  summary_i18n?: InternationalizedString;
+  /**
+   * More information about the merchant
+   */
+  merchant: MerchantInfo;
 }
 ```
 ```typescript
@@ -3082,6 +3235,7 @@ export declare enum RefreshReason {
   Refund = "refund",
   AbortPay = "abort-pay",
   AbortDeposit = "abort-deposit",
+  AbortPeerPushDebit = "abort-peer-push-debit",
   Recoup = "recoup",
   BackupRestored = "backup-restored",
   Scheduled = "scheduled",
@@ -3214,8 +3368,39 @@ export interface TransactionPeerPushDebit extends TransactionCommon {
 }
 ```
 ```typescript
+/**
+ * Internal withdrawal operation, only reported on request.
+ *
+ * Some transactions (peer-*-credit) internally do a withdrawal,
+ * but only the peer-*-credit transaction is reported.
+ *
+ * The internal withdrawal transaction allows to access the details of
+ * the underlying withdrawal for testing/debugging.
+ *
+ * It is usually not reported, so that amounts of transactions properly
+ * add up, since the amountEffecive of the withdrawal is already reported
+ * in the peer-*-credit transaction.
+ */
+export interface TransactionInternalWithdrawal extends TransactionCommon {
+  type: TransactionType.InternalWithdrawal;
+  /**
+   * Exchange of the withdrawal.
+   */
+  exchangeBaseUrl: string;
+  /**
+   * Amount that got subtracted from the reserve balance.
+   */
+  amountRaw: AmountString;
+  /**
+   * Amount that actually was (or will be) added to the wallet's balance.
+   */
+  amountEffective: AmountString;
+  withdrawalDetails: WithdrawalDetails;
+}
+```
+```typescript
 export interface AbortTransactionRequest {
-  transactionId: string;
+  transactionId: TransactionIdStr;
 }
 ```
 ```typescript
@@ -3279,7 +3464,7 @@ export type PreparePayResult =
 ```typescript
 export interface PreparePayResultInsufficientBalance {
   status: PreparePayResultType.InsufficientBalance;
-  transactionId: string;
+  transactionId: TransactionIdStr;
   proposalId: string;
   contractTerms: MerchantContractTerms;
   amountRaw: string;
@@ -3465,7 +3650,7 @@ export interface PayMerchantInsufficientBalanceDetails {
 ```typescript
 export interface PreparePayResultAlreadyConfirmed {
   status: PreparePayResultType.AlreadyConfirmed;
-  transactionId: string;
+  transactionId: TransactionIdStr;
   contractTerms: MerchantContractTerms;
   paid: boolean;
   amountRaw: string;
@@ -3481,7 +3666,7 @@ export interface PreparePayResultAlreadyConfirmed {
  */
 export interface PreparePayResultPaymentPossible {
   status: PreparePayResultType.PaymentPossible;
-  transactionId: string;
+  transactionId: TransactionIdStr;
   /**
    * @deprecated use transactionId instead
    */