commit 2b46ac8d738dc39c2199a05a01402d25f3e5f9cf
parent cffab8d7b3315c731ce0102ce084736771fc550d
Author: Florian Dold <florian@dold.me>
Date: Wed, 31 Jan 2024 00:11:48 +0100
update wallet-core docs
Diffstat:
| M | wallet/wallet-core.md | | | 428 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++---------- |
1 file changed, 378 insertions(+), 50 deletions(-)
diff --git a/wallet/wallet-core.md b/wallet/wallet-core.md
@@ -15,8 +15,10 @@ This file is auto-generated from [wallet-core](https://git.taler.net/wallet-core
* [ConvertWithdrawalAmountOp](#convertwithdrawalamountop)
### Managing Transactions
* [GetTransactionsOp](#gettransactionsop)
+* [ListAssociatedRefreshesOp](#listassociatedrefreshesop)
* [TestingGetSampleTransactionsOp](#testinggetsampletransactionsop)
* [GetTransactionByIdOp](#gettransactionbyidop)
+* [GetWithdrawalTransactionByUriOp](#getwithdrawaltransactionbyuriop)
* [RetryPendingNowOp](#retrypendingnowop)
* [DeleteTransactionOp](#deletetransactionop)
* [RetryTransactionOp](#retrytransactionop)
@@ -37,12 +39,20 @@ This file is auto-generated from [wallet-core](https://git.taler.net/wallet-core
* [ConfirmPayOp](#confirmpayop)
* [StartRefundQueryForUriOp](#startrefundqueryforuriop)
* [StartRefundQueryOp](#startrefundqueryop)
+### Global Currency management
+* [ListGlobalCurrencyAuditorsOp](#listglobalcurrencyauditorsop)
+* [ListGlobalCurrencyExchangesOp](#listglobalcurrencyexchangesop)
+* [AddGlobalCurrencyExchangeOp](#addglobalcurrencyexchangeop)
+* [AddGlobalCurrencyAuditorOp](#addglobalcurrencyauditorop)
+* [RemoveGlobalCurrencyExchangeOp](#removeglobalcurrencyexchangeop)
+* [RemoveGlobalCurrencyAuditorOp](#removeglobalcurrencyauditorop)
### Rewards
* [PrepareTipOp](#preparetipop)
* [AcceptTipOp](#accepttipop)
### Exchange Management
* [ListExchangesOp](#listexchangesop)
* [ListExchangesForScopedCurrencyOp](#listexchangesforscopedcurrencyop)
+* [PrepareWithdrawExchangeOp](#preparewithdrawexchangeop)
* [AddExchangeOp](#addexchangeop)
* [UpdateExchangeEntryOp](#updateexchangeentryop)
* [ListKnownBankAccountsOp](#listknownbankaccountsop)
@@ -51,7 +61,9 @@ This file is auto-generated from [wallet-core](https://git.taler.net/wallet-core
* [SetExchangeTosAcceptedOp](#setexchangetosacceptedop)
* [GetExchangeTosOp](#getexchangetosop)
* [GetExchangeDetailedInfoOp](#getexchangedetailedinfoop)
-* [ListCurrenciesOp](#listcurrenciesop)
+* [GetExchangeEntryByUrlOp](#getexchangeentrybyurlop)
+* [GetExchangeResourcesOp](#getexchangeresourcesop)
+* [DeleteExchangeOp](#deleteexchangeop)
* [GetCurrencySpecificationOp](#getcurrencyspecificationop)
### Deposits
* [GenerateDepositGroupTxIdOp](#generatedepositgrouptxidop)
@@ -398,6 +410,20 @@ export interface TransactionsRequest {
```
+### ListAssociatedRefreshesOp
+```typescript
+/**
+ * List refresh transactions associated with another transaction.
+ */
+export type ListAssociatedRefreshesOp = {
+ op: WalletApiOperation.ListAssociatedRefreshes;
+ request: ListAssociatedRefreshesRequest;
+ response: ListAssociatedRefreshesResponse;
+};
+// ListAssociatedRefreshes = "listAssociatedRefreshes"
+
+```
+
### TestingGetSampleTransactionsOp
```typescript
/**
@@ -429,6 +455,23 @@ export interface TransactionByIdRequest {
```
+### GetWithdrawalTransactionByUriOp
+```typescript
+export type GetWithdrawalTransactionByUriOp = {
+ op: WalletApiOperation.GetWithdrawalTransactionByUri;
+ request: WithdrawalTransactionByURIRequest;
+ response: TransactionWithdrawal | undefined;
+};
+// GetWithdrawalTransactionByUri = "getWithdrawalTransactionByUri"
+
+```
+```typescript
+export interface WithdrawalTransactionByURIRequest {
+ talerWithdrawUri: string;
+}
+
+```
+
### RetryPendingNowOp
```typescript
export type RetryPendingNowOp = {
@@ -554,7 +597,7 @@ export type ResumeTransactionOp = {
export type GetWithdrawalDetailsForAmountOp = {
op: WalletApiOperation.GetWithdrawalDetailsForAmount;
request: GetWithdrawalDetailsForAmountRequest;
- response: ManualWithdrawalDetails;
+ response: WithdrawalDetailsForAmount;
};
// GetWithdrawalDetailsForAmount = "getWithdrawalDetailsForAmount"
@@ -568,10 +611,12 @@ export interface GetWithdrawalDetailsForAmountRequest {
```
```typescript
-export interface ManualWithdrawalDetails {
+export interface WithdrawalDetailsForAmount {
/**
* Did the user accept the current version of the exchange's
* terms of service?
+ *
+ * @deprecated the client should query the exchange entry instead
*/
tosAccepted: boolean;
/**
@@ -591,18 +636,22 @@ export interface ManualWithdrawalDetails {
/**
* Ways to pay the exchange.
*
- * @deprecated in favor of withdrawalAccountList
+ * @deprecated in favor of withdrawalAccountsList
*/
paytoUris: string[];
/**
* Ways to pay the exchange, including accounts that require currency conversion.
*/
- withdrawalAccountList: WithdrawalExchangeAccountDetails[];
+ withdrawalAccountsList: WithdrawalExchangeAccountDetails[];
/**
* If the exchange supports age-restricted coins it will return
* the array of ages.
*/
ageRestrictionOptions?: number[];
+ /**
+ * Scope info of the currency withdrawn.
+ */
+ scopeInfo: ScopeInfo;
}
```
@@ -624,17 +673,29 @@ export type GetWithdrawalDetailsForUriOp = {
export interface GetWithdrawalDetailsForUriRequest {
talerWithdrawUri: string;
restrictAge?: number;
+ notifyChangeFromPendingTimeoutMs?: number;
}
```
```typescript
export interface WithdrawUriInfoResponse {
+ operationId: string;
+ status: WithdrawalOperationStatus;
+ confirmTransferUrl?: string;
amount: AmountString;
defaultExchangeBaseUrl?: string;
possibleExchanges: ExchangeListItem[];
}
```
+```typescript
+export type WithdrawalOperationStatus =
+ | "pending"
+ | "selected"
+ | "aborted"
+ | "confirmed";
+
+```
### AcceptBankIntegratedWithdrawalOp
```typescript
@@ -692,6 +753,8 @@ export interface AcceptManualWithdrawalRequest {
export interface AcceptManualWithdrawalResult {
/**
* Payto URIs that can be used to fund the withdrawal.
+ *
+ * @deprecated in favor of withdrawalAccountsList
*/
exchangePaytoUris: string[];
/**
@@ -927,6 +990,124 @@ export interface StartRefundQueryRequest {
```
+### ListGlobalCurrencyAuditorsOp
+```typescript
+export type ListGlobalCurrencyAuditorsOp = {
+ op: WalletApiOperation.ListGlobalCurrencyAuditors;
+ request: EmptyObject;
+ response: ListGlobalCurrencyAuditorsResponse;
+};
+// ListGlobalCurrencyAuditors = "listGlobalCurrencyAuditors"
+
+```
+```typescript
+export interface ListGlobalCurrencyAuditorsResponse {
+ auditors: {
+ currency: string;
+ auditorBaseUrl: string;
+ auditorPub: string;
+ }[];
+}
+
+```
+
+### ListGlobalCurrencyExchangesOp
+```typescript
+export type ListGlobalCurrencyExchangesOp = {
+ op: WalletApiOperation.ListGlobalCurrencyExchanges;
+ request: EmptyObject;
+ response: ListGlobalCurrencyExchangesResponse;
+};
+// ListGlobalCurrencyExchanges = "listGlobalCurrencyExchanges"
+
+```
+```typescript
+export interface ListGlobalCurrencyExchangesResponse {
+ exchanges: {
+ currency: string;
+ exchangeBaseUrl: string;
+ exchangeMasterPub: string;
+ }[];
+}
+
+```
+
+### AddGlobalCurrencyExchangeOp
+```typescript
+export type AddGlobalCurrencyExchangeOp = {
+ op: WalletApiOperation.AddGlobalCurrencyExchange;
+ request: AddGlobalCurrencyExchangeRequest;
+ response: EmptyObject;
+};
+// AddGlobalCurrencyExchange = "addGlobalCurrencyExchange"
+
+```
+```typescript
+export interface AddGlobalCurrencyExchangeRequest {
+ currency: string;
+ exchangeBaseUrl: string;
+ exchangeMasterPub: string;
+}
+
+```
+
+### AddGlobalCurrencyAuditorOp
+```typescript
+export type AddGlobalCurrencyAuditorOp = {
+ op: WalletApiOperation.AddGlobalCurrencyAuditor;
+ request: AddGlobalCurrencyAuditorRequest;
+ response: EmptyObject;
+};
+// AddGlobalCurrencyAuditor = "addGlobalCurrencyAuditor"
+
+```
+```typescript
+export interface AddGlobalCurrencyAuditorRequest {
+ currency: string;
+ auditorBaseUrl: string;
+ auditorPub: string;
+}
+
+```
+
+### RemoveGlobalCurrencyExchangeOp
+```typescript
+export type RemoveGlobalCurrencyExchangeOp = {
+ op: WalletApiOperation.RemoveGlobalCurrencyExchange;
+ request: RemoveGlobalCurrencyExchangeRequest;
+ response: EmptyObject;
+};
+// RemoveGlobalCurrencyExchange = "removeGlobalCurrencyExchange"
+
+```
+```typescript
+export interface RemoveGlobalCurrencyExchangeRequest {
+ currency: string;
+ exchangeBaseUrl: string;
+ exchangeMasterPub: string;
+}
+
+```
+
+### RemoveGlobalCurrencyAuditorOp
+```typescript
+export type RemoveGlobalCurrencyAuditorOp = {
+ op: WalletApiOperation.RemoveGlobalCurrencyAuditor;
+ request: RemoveGlobalCurrencyAuditorRequest;
+ response: EmptyObject;
+};
+// RemoveGlobalCurrencyAuditor = "removeGlobalCurrencyAuditor"
+
+```
+```typescript
+export interface RemoveGlobalCurrencyAuditorRequest {
+ currency: string;
+ auditorBaseUrl: string;
+ auditorPub: string;
+}
+
+```
+
### PrepareTipOp
```typescript
/**
@@ -1070,6 +1251,45 @@ export interface ShortExchangeListItem {
```
+### PrepareWithdrawExchangeOp
+```typescript
+/**
+ * Prepare for withdrawing via a taler://withdraw-exchange URI.
+ */
+export type PrepareWithdrawExchangeOp = {
+ op: WalletApiOperation.PrepareWithdrawExchange;
+ request: PrepareWithdrawExchangeRequest;
+ response: PrepareWithdrawExchangeResponse;
+};
+// PrepareWithdrawExchange = "prepareWithdrawExchange"
+
+```
+```typescript
+export interface PrepareWithdrawExchangeRequest {
+ /**
+ * A taler://withdraw-exchange URI.
+ */
+ talerUri: string;
+}
+
+```
+```typescript
+export interface PrepareWithdrawExchangeResponse {
+ /**
+ * Base URL of the exchange that already existed
+ * or was ephemerally added as an exchange entry to
+ * the wallet.
+ */
+ exchangeBaseUrl: string;
+ /**
+ * Amount from the taler://withdraw-exchange URI.
+ * Only present if specified in the URI.
+ */
+ amount?: AmountString;
+}
+
+```
+
### AddExchangeOp
```typescript
/**
@@ -1100,6 +1320,7 @@ export type UpdateExchangeEntryOp = {
```typescript
export interface UpdateExchangeEntryRequest {
exchangeBaseUrl: string;
+ force?: boolean;
}
```
@@ -1264,6 +1485,7 @@ export type GetExchangeTosOp = {
export interface GetExchangeTosRequest {
exchangeBaseUrl: string;
acceptedFormat?: string[];
+ acceptLanguage?: string;
}
```
@@ -1286,6 +1508,16 @@ export interface GetExchangeTosResult {
* Accepted content type
*/
contentType: string;
+ /**
+ * Language of the returned content.
+ *
+ * If missing, language is unknown.
+ */
+ contentLanguage: string | undefined;
+ /**
+ * Available languages as advertised by the exchange.
+ */
+ tosAvailableLanguages: string[];
tosStatus: ExchangeTosStatus;
}
@@ -1350,31 +1582,69 @@ export interface FeeDescription {
```
-### ListCurrenciesOp
+### GetExchangeEntryByUrlOp
```typescript
/**
- * List currencies known to the wallet.
+ * Get the current terms of a service of an exchange.
*/
-export type ListCurrenciesOp = {
- op: WalletApiOperation.ListCurrencies;
- request: EmptyObject;
- response: WalletCurrencyInfo;
+export type GetExchangeEntryByUrlOp = {
+ op: WalletApiOperation.GetExchangeEntryByUrl;
+ request: GetExchangeEntryByUrlRequest;
+ response: GetExchangeEntryByUrlResponse;
};
-// ListCurrencies = "listCurrencies"
+// GetExchangeEntryByUrl = "getExchangeEntryByUrl"
```
```typescript
-export interface WalletCurrencyInfo {
- trustedAuditors: {
- currency: string;
- auditorPub: string;
- auditorBaseUrl: string;
- }[];
- trustedExchanges: {
- currency: string;
- exchangeMasterPub: string;
- exchangeBaseUrl: string;
- }[];
+export interface GetExchangeEntryByUrlRequest {
+ exchangeBaseUrl: string;
+}
+
+```
+
+### GetExchangeResourcesOp
+```typescript
+/**
+ * Get resources associated with an exchange.
+ */
+export type GetExchangeResourcesOp = {
+ op: WalletApiOperation.GetExchangeResources;
+ request: GetExchangeResourcesRequest;
+ response: GetExchangeResourcesResponse;
+};
+// GetExchangeResources = "getExchangeResources"
+
+```
+```typescript
+export interface GetExchangeResourcesRequest {
+ exchangeBaseUrl: string;
+}
+
+```
+```typescript
+export interface GetExchangeResourcesResponse {
+ hasResources: boolean;
+}
+
+```
+
+### DeleteExchangeOp
+```typescript
+/**
+ * Get resources associated with an exchange.
+ */
+export type DeleteExchangeOp = {
+ op: WalletApiOperation.GetExchangeResources;
+ request: DeleteExchangeRequest;
+ response: EmptyObject;
+};
+// GetExchangeResources = "getExchangeResources"
+
+```
+```typescript
+export interface DeleteExchangeRequest {
+ exchangeBaseUrl: string;
+ purge?: boolean;
}
```
@@ -1401,18 +1671,6 @@ export interface GetCurrencySpecificationResponse {
}
```
-```typescript
-export interface CurrencySpecification {
- name: string;
- num_fractional_input_digits: Integer;
- num_fractional_normal_digits: Integer;
- num_fractional_trailing_zero_digits: Integer;
- alt_unit_names: {
- [log10: string]: string;
- };
-}
-
-```
### GenerateDepositGroupTxIdOp
```typescript
@@ -1908,6 +2166,17 @@ export interface CheckPeerPushDebitRequest {
export interface CheckPeerPushDebitResponse {
amountRaw: AmountString;
amountEffective: AmountString;
+ exchangeBaseUrl: string;
+ /**
+ * Maximum expiration date, based on how close the coins
+ * used for the payment are to expiry.
+ *
+ * The value is based on when the wallet would typically
+ * automatically refresh the coins on its own, leaving enough
+ * time to get a refund for the push payment and refresh the
+ * coin.
+ */
+ maxExpirationDate: TalerProtocolTimestamp;
}
```
@@ -1965,14 +2234,18 @@ export interface PreparePeerPushCreditRequest {
```typescript
export interface PreparePeerPushCreditResponse {
contractTerms: PeerContractTerms;
+ amountRaw: AmountString;
+ amountEffective: AmountString;
+ transactionId: string;
+ exchangeBaseUrl: string;
+ /**
+ * @deprecated use transaction ID instead.
+ */
+ peerPushCreditId: string;
/**
* @deprecated
*/
amount: AmountString;
- amountRaw: AmountString;
- amountEffective: AmountString;
- peerPushCreditId: string;
- transactionId: string;
}
```
@@ -2172,8 +2445,8 @@ export type ExportDbOp = {
```typescript
export type ImportDbOp = {
op: WalletApiOperation.ImportDb;
- request: any;
- response: any;
+ request: ImportDbRequest;
+ response: EmptyObject;
};
// ImportDb = "importDb"
@@ -3020,15 +3293,27 @@ export interface ForceRefreshRequest {
## Common Declarations
```typescript
export interface WalletCoreVersion {
+ implementationSemver: string;
+ implementationGitHash: string;
/**
- * @deprecated
+ * Wallet-core protocol version supported by this implementation
+ * of the API ("server" version).
*/
- hash: string | undefined;
version: string;
exchange: string;
merchant: string;
+ bankIntegrationApiRange: string;
+ bankConversionApiRange: string;
+ corebankApiRange: string;
+ /**
+ * @deprecated as bank was split into multiple APIs with separate versioning
+ */
bank: string;
/**
+ * @deprecated
+ */
+ hash: string | undefined;
+ /**
* @deprecated will be removed
*/
devMode: boolean;
@@ -3228,6 +3513,7 @@ export declare enum TransactionMinorState {
CheckRefund = "check-refund",
CreatePurse = "create-purse",
DeletePurse = "delete-purse",
+ RefreshExpired = "refresh-expired",
Ready = "ready",
Merge = "merge",
Repurchase = "repurchase",
@@ -3321,17 +3607,49 @@ export interface WithdrawalExchangeAccountDetails {
*/
paytoUri: string;
/**
+ * Status that indicates whether the account can be used
+ * by the user to send funds for a withdrawal.
+ *
+ * ok: account should be shown to the user
+ * error: account should not be shown to the user, UIs might render the error (in conversionError),
+ * especially in dev mode.
+ */
+ status: "ok" | "error";
+ /**
* Transfer amount. Might be in a different currency than the requested
* amount for withdrawal.
*
* Redundant with the amount in paytoUri, just included to avoid parsing.
+ *
+ * Only included if this account does a currency conversion.
+ */
+ transferAmount?: AmountString;
+ /**
+ * Currency specification for the external currency.
+ *
+ * Only included if this account requires a currency conversion.
*/
- transferAmount: AmountString;
+ currencySpecification?: CurrencySpecification;
/**
* Further restrictions for sending money to the
* exchange.
*/
creditRestrictions?: AccountRestriction[];
+ /**
+ * Error that happened when attempting to request the conversion rate.
+ */
+ conversionError?: TalerErrorDetail;
+}
+```
+```typescript
+export interface CurrencySpecification {
+ name: string;
+ num_fractional_input_digits: Integer;
+ num_fractional_normal_digits: Integer;
+ num_fractional_trailing_zero_digits: Integer;
+ alt_unit_names: {
+ [log10: string]: string;
+ };
}
```
```typescript
@@ -3376,6 +3694,7 @@ interface WithdrawalDetailsForTalerBankIntegrationApi {
* Is the reserve ready for withdrawal?
*/
reserveIsReady: boolean;
+ exchangeCreditAccountDetails?: WithdrawalExchangeAccountDetails[];
}
```
```typescript
@@ -3569,6 +3888,7 @@ export declare enum RefreshReason {
AbortPay = "abort-pay",
AbortDeposit = "abort-deposit",
AbortPeerPushDebit = "abort-peer-push-debit",
+ AbortPeerPullDebit = "abort-peer-pull-debit",
Recoup = "recoup",
BackupRestored = "backup-restored",
Scheduled = "scheduled",
@@ -3632,8 +3952,10 @@ export interface TransactionPeerPullCredit extends TransactionCommon {
amountEffective: AmountString;
/**
* URI to send to the other party.
+ *
+ * Only available in the right state.
*/
- talerUri: string;
+ talerUri: string | undefined;
}
```
```typescript
@@ -3743,6 +4065,9 @@ export interface AbortTransactionRequest {
}
```
```typescript
+/**
+ * Info about an exchange entry in the wallet.
+ */
export interface ExchangeListItem {
exchangeBaseUrl: string;
currency: string | undefined;
@@ -3751,6 +4076,7 @@ export interface ExchangeListItem {
exchangeEntryStatus: ExchangeEntryStatus;
exchangeUpdateStatus: ExchangeUpdateStatus;
ageRestrictionOptions: number[];
+ scopeInfo: ScopeInfo | undefined;
/**
* Information about the last error that occurred when trying
* to update the exchange info.
@@ -3775,12 +4101,11 @@ export declare enum ExchangeEntryStatus {
```typescript
export declare enum ExchangeUpdateStatus {
Initial = "initial",
- InitialUpdate = "initial(update)",
+ InitialUpdate = "initial-update",
Suspended = "suspended",
- Failed = "failed",
- OutdatedUpdate = "outdated(update)",
+ UnavailableUpdate = "unavailable-update",
Ready = "ready",
- ReadyUpdate = "ready(update)",
+ ReadyUpdate = "ready-update",
}
```
```typescript
@@ -4062,8 +4387,11 @@ export interface ForcedCoinSel {
```typescript
export interface AddExchangeRequest {
exchangeBaseUrl: string;
- masterPub?: string;
+ /**
+ * @deprecated use a separate API call to start a forced exchange update instead
+ */
forceUpdate?: boolean;
+ masterPub?: string;
}
```
```typescript
