diff options
Diffstat (limited to 'wallet/wallet-core.md')
| -rw-r--r-- | wallet/wallet-core.md | 518 |
1 files changed, 396 insertions, 122 deletions
diff --git a/wallet/wallet-core.md b/wallet/wallet-core.md index 2e34fb4f..977e100d 100644 --- 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,17 @@ This file is auto-generated from [wallet-core](https://git.taler.net/wallet-core * [ConfirmPayOp](#confirmpayop) * [StartRefundQueryForUriOp](#startrefundqueryforuriop) * [StartRefundQueryOp](#startrefundqueryop) -### Rewards -* [PrepareTipOp](#preparetipop) -* [AcceptTipOp](#accepttipop) +### Global Currency management +* [ListGlobalCurrencyAuditorsOp](#listglobalcurrencyauditorsop) +* [ListGlobalCurrencyExchangesOp](#listglobalcurrencyexchangesop) +* [AddGlobalCurrencyExchangeOp](#addglobalcurrencyexchangeop) +* [AddGlobalCurrencyAuditorOp](#addglobalcurrencyauditorop) +* [RemoveGlobalCurrencyExchangeOp](#removeglobalcurrencyexchangeop) +* [RemoveGlobalCurrencyAuditorOp](#removeglobalcurrencyauditorop) ### Exchange Management * [ListExchangesOp](#listexchangesop) * [ListExchangesForScopedCurrencyOp](#listexchangesforscopedcurrencyop) +* [PrepareWithdrawExchangeOp](#preparewithdrawexchangeop) * [AddExchangeOp](#addexchangeop) * [UpdateExchangeEntryOp](#updateexchangeentryop) * [ListKnownBankAccountsOp](#listknownbankaccountsop) @@ -51,7 +58,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) @@ -377,9 +386,17 @@ export type GetTransactionsOp = { export interface TransactionsRequest { /** * return only transactions in the given currency + * + * it will be removed in next release + * + * @deprecated use scopeInfo */ currency?: string; /** + * return only transactions in the given scopeInfo + */ + scopeInfo?: ScopeInfo; + /** * if present, results will be limited to transactions related to the given search string */ search?: string; @@ -398,6 +415,32 @@ export interface TransactionsRequest { ``` +### ListAssociatedRefreshesOp +```typescript +/** + * List refresh transactions associated with another transaction. + */ +export type ListAssociatedRefreshesOp = { + op: WalletApiOperation.ListAssociatedRefreshes; + request: ListAssociatedRefreshesRequest; + response: ListAssociatedRefreshesResponse; +}; +// ListAssociatedRefreshes = "listAssociatedRefreshes" + +``` +```typescript +export interface ListAssociatedRefreshesRequest { + transactionId: string; +} + +``` +```typescript +export interface ListAssociatedRefreshesResponse { + transactionIds: string[]; +} + +``` + ### TestingGetSampleTransactionsOp ```typescript /** @@ -429,6 +472,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 +614,7 @@ export type ResumeTransactionOp = { export type GetWithdrawalDetailsForAmountOp = { op: WalletApiOperation.GetWithdrawalDetailsForAmount; request: GetWithdrawalDetailsForAmountRequest; - response: ManualWithdrawalDetails; + response: WithdrawalDetailsForAmount; }; // GetWithdrawalDetailsForAmount = "getWithdrawalDetailsForAmount" @@ -568,10 +628,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 +653,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 +690,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 +770,8 @@ export interface AcceptManualWithdrawalRequest { export interface AcceptManualWithdrawalResult { /** * Payto URIs that can be used to fund the withdrawal. + * + * @deprecated in favor of withdrawalAccountsList */ exchangePaytoUris: string[]; /** @@ -854,7 +934,7 @@ export interface ConfirmPayRequest { * @deprecated use transactionId instead */ proposalId?: string; - transactionId?: string; + transactionId?: TransactionIdStr; sessionId?: string; forcedCoinSel?: ForcedCoinSel; } @@ -905,6 +985,9 @@ export interface PrepareRefundRequest { ``` ```typescript export interface StartRefundQueryForUriResponse { + /** + * Transaction id of the *payment* where the refund query was started. + */ transactionId: TransactionIdStr; } @@ -927,92 +1010,120 @@ export interface StartRefundQueryRequest { ``` -### PrepareTipOp +### ListGlobalCurrencyAuditorsOp ```typescript -/** - * Query and store information about a reward. - */ -export type PrepareTipOp = { - op: WalletApiOperation.PrepareReward; - request: PrepareRewardRequest; - response: PrepareRewardResult; +export type ListGlobalCurrencyAuditorsOp = { + op: WalletApiOperation.ListGlobalCurrencyAuditors; + request: EmptyObject; + response: ListGlobalCurrencyAuditorsResponse; }; -// PrepareReward = "prepareReward" +// ListGlobalCurrencyAuditors = "listGlobalCurrencyAuditors" ``` ```typescript -export interface PrepareRewardRequest { - talerRewardUri: string; +export interface ListGlobalCurrencyAuditorsResponse { + auditors: { + currency: string; + auditorBaseUrl: string; + auditorPub: string; + }[]; } ``` + +### ListGlobalCurrencyExchangesOp ```typescript -export interface PrepareTipResult { - /** - * Unique ID for the tip assigned by the wallet. - * Typically different from the merchant-generated tip ID. - * - * @deprecated use transactionId instead - */ - walletRewardId: string; - /** - * Tip transaction ID. - */ - transactionId: string; - /** - * Has the tip already been accepted? - */ - accepted: boolean; - /** - * Amount that the merchant gave. - */ - rewardAmountRaw: AmountString; - /** - * Amount that arrived at the wallet. - * Might be lower than the raw amount due to fees. - */ - rewardAmountEffective: AmountString; - /** - * Base URL of the merchant backend giving then tip. - */ - merchantBaseUrl: string; - /** - * Base URL of the exchange that is used to withdraw the tip. - * Determined by the merchant, the wallet/user has no choice here. - */ +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; - /** - * Time when the tip will expire. After it expired, it can't be picked - * up anymore. - */ - expirationTimestamp: TalerProtocolTimestamp; + exchangeMasterPub: string; } ``` -### AcceptTipOp +### AddGlobalCurrencyAuditorOp ```typescript -/** - * Accept a reward. - */ -export type AcceptTipOp = { - op: WalletApiOperation.AcceptReward; - request: AcceptRewardRequest; - response: AcceptTipResponse; +export type AddGlobalCurrencyAuditorOp = { + op: WalletApiOperation.AddGlobalCurrencyAuditor; + request: AddGlobalCurrencyAuditorRequest; + response: EmptyObject; }; -// AcceptReward = "acceptReward" +// AddGlobalCurrencyAuditor = "addGlobalCurrencyAuditor" ``` ```typescript -export interface AcceptRewardRequest { - walletRewardId: string; +export interface AddGlobalCurrencyAuditorRequest { + currency: string; + auditorBaseUrl: string; + auditorPub: string; } ``` + +### RemoveGlobalCurrencyExchangeOp ```typescript -export interface AcceptTipResponse { - transactionId: TransactionIdStr; - next_url?: string; +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; } ``` @@ -1070,6 +1181,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 +1250,7 @@ export type UpdateExchangeEntryOp = { ```typescript export interface UpdateExchangeEntryRequest { exchangeBaseUrl: string; + force?: boolean; } ``` @@ -1264,6 +1415,7 @@ export type GetExchangeTosOp = { export interface GetExchangeTosRequest { exchangeBaseUrl: string; acceptedFormat?: string[]; + acceptLanguage?: string; } ``` @@ -1286,6 +1438,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 +1512,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 +1601,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 @@ -1462,7 +1650,7 @@ export interface CreateDepositGroupRequest { * that occur while the operation has been created but * before the creation request has returned. */ - transactionId?: string; + transactionId?: TransactionIdStr; depositPaytoUri: string; amount: AmountString; } @@ -1908,6 +2096,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 +2164,18 @@ export interface PreparePeerPushCreditRequest { ```typescript export interface PreparePeerPushCreditResponse { contractTerms: PeerContractTerms; + amountRaw: AmountString; + amountEffective: AmountString; + transactionId: TransactionIdStr; + exchangeBaseUrl: string; + /** + * @deprecated use transaction ID instead. + */ + peerPushCreditId: string; /** * @deprecated */ amount: AmountString; - amountRaw: AmountString; - amountEffective: AmountString; - peerPushCreditId: string; - transactionId: string; } ``` @@ -2100,7 +2303,7 @@ export interface PreparePeerPullDebitResponse { amountRaw: AmountString; amountEffective: AmountString; peerPullDebitId: string; - transactionId: string; + transactionId: TransactionIdStr; } ``` @@ -2126,7 +2329,7 @@ export interface ConfirmPeerPullDebitRequest { * @deprecated use transactionId instead */ peerPullDebitId?: string; - transactionId?: string; + transactionId?: TransactionIdStr; } ``` @@ -2172,12 +2375,18 @@ export type ExportDbOp = { ```typescript export type ImportDbOp = { op: WalletApiOperation.ImportDb; - request: any; - response: any; + request: ImportDbRequest; + response: EmptyObject; }; // ImportDb = "importDb" ``` +```typescript +export interface ImportDbRequest { + dump: any; +} + +``` ### ClearDbOp ```typescript @@ -2968,7 +3177,7 @@ export type TestingWaitTransactionStateOp = { ``` ```typescript export interface TestingWaitTransactionRequest { - transactionId: string; + transactionId: TransactionIdStr; txState: TransactionState; } @@ -3020,15 +3229,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; @@ -3089,7 +3310,8 @@ export type Transaction = | TransactionPeerPullDebit | TransactionPeerPushCredit | TransactionPeerPushDebit - | TransactionInternalWithdrawal; + | TransactionInternalWithdrawal + | TransactionRecoup; ``` ```typescript /** @@ -3159,6 +3381,7 @@ export declare enum TransactionType { PeerPushCredit = "peer-push-credit", PeerPullDebit = "peer-pull-debit", PeerPullCredit = "peer-pull-credit", + Recoup = "recoup", } ``` ```typescript @@ -3228,6 +3451,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 +3545,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 +3632,7 @@ interface WithdrawalDetailsForTalerBankIntegrationApi { * Is the reserve ready for withdrawal? */ reserveIsReady: boolean; + exchangeCreditAccountDetails?: WithdrawalExchangeAccountDetails[]; } ``` ```typescript @@ -3569,6 +3826,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 +3890,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 @@ -3738,11 +3998,22 @@ export interface TransactionInternalWithdrawal extends TransactionCommon { } ``` ```typescript +/** + * The exchange revoked a key and the wallet recoups funds. + */ +export interface TransactionRecoup extends TransactionCommon { + type: TransactionType.Recoup; +} +``` +```typescript export interface AbortTransactionRequest { transactionId: TransactionIdStr; } ``` ```typescript +/** + * Info about an exchange entry in the wallet. + */ export interface ExchangeListItem { exchangeBaseUrl: string; currency: string | undefined; @@ -3751,6 +4022,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 +4047,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 +4333,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 |