taler-docs

commit 5eb68373bb0b4ceea3d9523b23d5adb98de74a6b
parent 488a85f7a7340ab4e3e022a78dee8eee85e01b85
Author: Florian Dold <florian@dold.me>
Date:   Mon, 17 Feb 2025 22:10:10 +0100

update wallet-core API docs

Diffstat:
M
wallet/wallet-core.md
 | 
88
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++----------

1 file changed, 77 insertions(+), 11 deletions(-)
diff --git a/wallet/wallet-core.md b/wallet/wallet-core.md
@@ -1222,7 +1222,7 @@ export type ConfirmPayResult = ConfirmPayResultDone | ConfirmPayResultPending;
  */
 export interface ConfirmPayResultDone {
   type: ConfirmPayResultType.Done;
-  contractTerms: MerchantContractTerms;
+  contractTerms: MerchantContractTermsV0;
   transactionId: TransactionIdStr;
 }
 
@@ -3100,7 +3100,7 @@ export type TestCryptoOp = {
 export type WithdrawTestBalanceOp = {
   op: WalletApiOperation.WithdrawTestBalance;
   request: WithdrawTestBalanceRequest;
-  response: EmptyObject;
+  response: WithdrawTestBalanceResult;
 };
 // WithdrawTestBalance = "withdrawTestBalance"
 
@@ -3142,7 +3142,7 @@ export interface WithdrawTestBalanceRequest {
 export type WithdrawTestkudosOp = {
   op: WalletApiOperation.WithdrawTestkudos;
   request: EmptyObject;
-  response: EmptyObject;
+  response: WithdrawTestBalanceResult;
 };
 // WithdrawTestkudos = "withdrawTestkudos"
 
@@ -3471,7 +3471,14 @@ export type TestingWaitTransactionStateOp = {
 ```typescript
 export interface TestingWaitTransactionRequest {
   transactionId: TransactionIdStr;
-  txState: TransactionState | TransactionState[];
+  txState: TransactionStatePattern | TransactionStatePattern[];
+}
+
+```
+```typescript
+export interface TransactionStatePattern {
+  major: TransactionMajorState | TransactionStateWildcard;
+  minor?: TransactionMinorState | TransactionStateWildcard;
 }
 
 ```
@@ -4723,7 +4730,6 @@ export interface ForcedDenomSel {
 ```
 ```typescript
 export interface AcceptWithdrawalResponse {
-  reservePub: string;
   confirmTransferUrl?: string;
   transactionId: TransactionIdStr;
 }
@@ -4748,25 +4754,31 @@ export interface PreparePayResultInsufficientBalance {
    * of *possible* payment providers.
    */
   scopes: ScopeInfo[];
-  contractTerms: MerchantContractTerms;
+  contractTerms: MerchantContractTermsV0;
   amountRaw: AmountString;
   talerUri: string;
   balanceDetails: PaymentInsufficientBalanceDetails;
 }
 ```
 ```typescript
+export interface MerchantContractTermsV0 extends MerchantContractTermsCommon {
+  version?: 0;
+  amount: AmountString;
+  max_fee: AmountString;
+}
+```
+```typescript
 /**
  * Contract terms from a merchant.
  * FIXME: Add type field!
  */
-export interface MerchantContractTerms {
+interface MerchantContractTermsCommon {
   h_wire: string;
   auto_refund?: TalerProtocolDuration;
   wire_method: string;
   summary: string;
   summary_i18n?: InternationalizedString;
   order_id: string;
-  amount: string;
   nonce: string;
   pay_deadline: TalerProtocolTimestamp;
   merchant: MerchantInfo;
@@ -4783,7 +4795,6 @@ export interface MerchantContractTerms {
   public_reorder_url?: string;
   fulfillment_message?: string;
   fulfillment_message_i18n?: InternationalizedString;
-  max_fee: string;
   extra?: any;
   minimum_age?: Integer;
 }
@@ -4835,17 +4846,60 @@ export interface PaymentInsufficientBalanceDetails {
       /**
        * Exchange doesn't have global fees configured for the relevant year,
        * p2p payments aren't possible.
+       *
+       * @deprecated use causeHint instead
        */
       missingGlobalFees: boolean;
+      /**
+       * Hint that UIs should show to explain the insufficient
+       * balance.
+       */
+      causeHint?: InsufficientBalanceHint | undefined;
     };
   };
 }
 ```
 ```typescript
+export declare enum InsufficientBalanceHint {
+  /**
+   *  Merchant doesn't accept money from exchange(s) that the wallet supports.
+   */
+  MerchantAcceptInsufficient = "merchant-accept-insufficient",
+  /**
+   * Merchant accepts funds from a matching exchange, but the funds can't be
+   * deposited with the wire method.
+   */
+  MerchantDepositInsufficient = "merchant-deposit-insufficient",
+  /**
+   * While in principle the balance is sufficient,
+   * the age restriction on coins causes the spendable
+   * balance to be insufficient.
+   */
+  MerchantAgeRestricted = "merchant-age-restricted",
+  /**
+   * While in principle the balance is sufficient,
+   * the age restriction on coins causes the spendable
+   * balance to be insufficient.
+   */
+  PeerAgeRestricted = "peer-age-restricted",
+  /**
+   * Wallet has enough available funds,
+   * but the material funds are insufficient. Usually because there is a
+   * pending refresh operation.
+   */
+  WalletMateriallyInsufficient = "wallet-materially-insufficient",
+  /**
+   * Exchange is missing the global fee configuration, thus fees are unknown
+   * and funds from this exchange can't be used for p2p payments.
+   */
+  ExchangeMissingGlobalFees = "exchange-missing-global-fees",
+}
+```
+```typescript
 export interface PreparePayResultAlreadyConfirmed {
   status: PreparePayResultType.AlreadyConfirmed;
   transactionId: TransactionIdStr;
-  contractTerms: MerchantContractTerms;
+  contractTerms: MerchantContractTermsV0;
   paid: boolean;
   amountRaw: AmountString;
   amountEffective: AmountString | undefined;
@@ -4864,7 +4918,7 @@ export interface PreparePayResultAlreadyConfirmed {
 export interface PreparePayResultPaymentPossible {
   status: PreparePayResultType.PaymentPossible;
   transactionId: TransactionIdStr;
-  contractTerms: MerchantContractTerms;
+  contractTerms: MerchantContractTermsV0;
   /**
    * Scopes involved in this transaction.
    */
@@ -5054,3 +5108,15 @@ export interface PeerContractTerms {
   purse_expiration: TalerProtocolTimestamp;
 }
 ```
+```typescript
+export interface WithdrawTestBalanceResult {
+  /**
+   * Transaction ID of the newly created withdrawal transaction.
+   */
+  transactionId: TransactionIdStr;
+  /**
+   * Account of the user registered for the withdrawal.
+   */
+  accountPaytoUri: string;
+}
+```