diff options
Diffstat (limited to 'wallet/wallet-core.md')
| -rw-r--r-- | wallet/wallet-core.md | 2507 |
1 files changed, 1539 insertions, 968 deletions
diff --git a/wallet/wallet-core.md b/wallet/wallet-core.md index d8262f96..8c600081 100644 --- a/wallet/wallet-core.md +++ b/wallet/wallet-core.md @@ -3,17 +3,28 @@ This file is auto-generated from [wallet-core](https://git.taler.net/wallet-core ## Overview ### Unknown Group * [InitWalletOp](#initwalletop) +* [SetWalletRunConfigOp](#setwalletrunconfigop) * [GetVersionOp](#getversionop) ### Basic Wallet Information * [GetBalancesOp](#getbalancesop) * [GetBalancesDetailOp](#getbalancesdetailop) +* [GetPlanForOperationOp](#getplanforoperationop) +* [ConvertDepositAmountOp](#convertdepositamountop) +* [GetMaxDepositAmountOp](#getmaxdepositamountop) +* [ConvertPeerPushAmountOp](#convertpeerpushamountop) +* [GetMaxPeerPushAmountOp](#getmaxpeerpushamountop) +* [ConvertWithdrawalAmountOp](#convertwithdrawalamountop) ### Managing Transactions * [GetTransactionsOp](#gettransactionsop) +* [ListAssociatedRefreshesOp](#listassociatedrefreshesop) +* [TestingGetSampleTransactionsOp](#testinggetsampletransactionsop) * [GetTransactionByIdOp](#gettransactionbyidop) +* [GetWithdrawalTransactionByUriOp](#getwithdrawaltransactionbyuriop) * [RetryPendingNowOp](#retrypendingnowop) * [DeleteTransactionOp](#deletetransactionop) * [RetryTransactionOp](#retrytransactionop) * [AbortTransactionOp](#aborttransactionop) +* [FailTransactionOp](#failtransactionop) * [SuspendTransactionOp](#suspendtransactionop) * [ResumeTransactionOp](#resumetransactionop) ### Withdrawals @@ -23,29 +34,39 @@ This file is auto-generated from [wallet-core](https://git.taler.net/wallet-core * [AcceptManualWithdrawalOp](#acceptmanualwithdrawalop) ### Merchant Payments * [PreparePayForUriOp](#preparepayforuriop) +* [SharePaymentOp](#sharepaymentop) * [PreparePayForTemplateOp](#preparepayfortemplateop) * [GetContractTermsDetailsOp](#getcontracttermsdetailsop) * [ConfirmPayOp](#confirmpayop) -* [ApplyRefundOp](#applyrefundop) -* [ApplyRefundFromPurchaseIdOp](#applyrefundfrompurchaseidop) -* [PrepareRefundOp](#preparerefundop) -### Tipping -* [PrepareTipOp](#preparetipop) -* [AcceptTipOp](#accepttipop) +* [StartRefundQueryForUriOp](#startrefundqueryforuriop) +* [StartRefundQueryOp](#startrefundqueryop) +### 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) * [AddKnownBankAccountsOp](#addknownbankaccountsop) * [ForgetKnownBankAccountsOp](#forgetknownbankaccountsop) * [SetExchangeTosAcceptedOp](#setexchangetosacceptedop) +* [SetExchangeTosForgottenOp](#setexchangetosforgottenop) * [GetExchangeTosOp](#getexchangetosop) * [GetExchangeDetailedInfoOp](#getexchangedetailedinfoop) -* [ListCurrenciesOp](#listcurrenciesop) +* [GetExchangeEntryByUrlOp](#getexchangeentrybyurlop) +* [GetExchangeResourcesOp](#getexchangeresourcesop) +* [DeleteExchangeOp](#deleteexchangeop) +* [GetCurrencySpecificationOp](#getcurrencyspecificationop) ### Deposits +* [GenerateDepositGroupTxIdOp](#generatedepositgrouptxidop) * [CreateDepositGroupOp](#createdepositgroupop) -* [TrackDepositGroupOp](#trackdepositgroupop) -* [GetFeeForDepositOp](#getfeefordepositop) * [PrepareDepositOp](#preparedepositop) ### Backups * [ExportBackupRecoveryOp](#exportbackuprecoveryop) @@ -56,7 +77,10 @@ This file is auto-generated from [wallet-core](https://git.taler.net/wallet-core * [RemoveBackupProviderOp](#removebackupproviderop) * [GetBackupInfoOp](#getbackupinfoop) * [SetWalletDeviceIdOp](#setwalletdeviceidop) -* [ExportBackupPlainOp](#exportbackupplainop) +* [ListStoredBackupsOp](#liststoredbackupsop) +* [CreateStoredBackupsOp](#createstoredbackupsop) +* [RecoverStoredBackupsOp](#recoverstoredbackupsop) +* [DeleteStoredBackupOp](#deletestoredbackupop) ### Peer Payments * [CheckPeerPushDebitOp](#checkpeerpushdebitop) * [InitiatePeerPushDebitOp](#initiatepeerpushdebitop) @@ -66,6 +90,8 @@ This file is auto-generated from [wallet-core](https://git.taler.net/wallet-core * [InitiatePeerPullCreditOp](#initiatepeerpullcreditop) * [PreparePeerPullDebitOp](#preparepeerpulldebitop) * [ConfirmPeerPullDebitOp](#confirmpeerpulldebitop) +### Data Validation +* [ValidateIbanOp](#validateibanop) ### Database Management * [ExportDbOp](#exportdbop) * [ImportDbOp](#importdbop) @@ -73,15 +99,22 @@ This file is auto-generated from [wallet-core](https://git.taler.net/wallet-core * [RecycleOp](#recycleop) ### Testing and Debugging * [ApplyDevExperimentOp](#applydevexperimentop) -* [SetDevModeOp](#setdevmodeop) * [RunIntegrationTestOp](#runintegrationtestop) +* [RunIntegrationTestV2Op](#runintegrationtestv2op) * [TestCryptoOp](#testcryptoop) * [WithdrawTestBalanceOp](#withdrawtestbalanceop) * [WithdrawTestkudosOp](#withdrawtestkudosop) * [TestPayOp](#testpayop) -* [WithdrawFakebankOp](#withdrawfakebankop) * [GetPendingTasksOp](#getpendingtasksop) +* [GetActiveTasksOp](#getactivetasksop) * [DumpCoinsOp](#dumpcoinsop) +* [TestingSetTimetravelOp](#testingsettimetravelop) +* [TestingListTasksForTransactionOp](#testinglisttasksfortransactionop) +* [TestingWaitTransactionsFinalOp](#testingwaittransactionsfinalop) +* [TestingWaitRefreshesFinalOp](#testingwaitrefreshesfinalop) +* [TestingWaitTransactionStateOp](#testingwaittransactionstateop) +* [TestingPingOp](#testingpingop) +* [TestingGetDenomStatsOp](#testinggetdenomstatsop) * [SetCoinSuspendedOp](#setcoinsuspendedop) * [ForceRefreshOp](#forcerefreshop) ## Operation Reference @@ -90,7 +123,7 @@ This file is auto-generated from [wallet-core](https://git.taler.net/wallet-core /** * Initialize wallet-core. * - * Must be the request before any other operations. + * Must be the first request made to wallet-core. */ export type InitWalletOp = { op: WalletApiOperation.InitWallet; @@ -100,16 +133,20 @@ export type InitWalletOp = { // InitWallet = "initWallet" ``` -```typescript -export interface InitRequest { - skipDefaults?: boolean; -} -``` +### SetWalletRunConfigOp ```typescript -export interface InitResponse { - versionInfo: WalletCoreVersion; -} +/** + * Change the configuration of wallet-core. + * + * Currently an alias for the initWallet request. + */ +export type SetWalletRunConfigOp = { + op: WalletApiOperation.SetWalletRunConfig; + request: InitRequest; + response: InitResponse; +}; +// SetWalletRunConfig = "setWalletRunConfig" ``` @@ -139,37 +176,40 @@ export type GetBalancesOp = { ``` ```typescript export interface BalancesResponse { - balances: Balance[]; + balances: WalletBalance[]; } ``` ```typescript -export interface Balance { +export interface WalletBalance { scopeInfo: ScopeInfo; available: AmountString; pendingIncoming: AmountString; pendingOutgoing: AmountString; + /** + * Does the balance for this currency have a pending + * transaction? + * + * @deprecated use flags and pendingIncoming/pendingOutgoing instead + */ hasPendingTransactions: boolean; + /** + * Is there a transaction that requires user input? + * + * @deprecated use flags instead + */ requiresUserInput: boolean; + flags: BalanceFlag[]; } ``` ```typescript -export type ScopeInfo = - | { - type: ScopeType.Global; - currency: string; - } - | { - type: ScopeType.Exchange; - currency: string; - url: string; - } - | { - type: ScopeType.Auditor; - currency: string; - url: string; - }; +export declare enum BalanceFlag { + IncomingKyc = "incoming-kyc", + IncomingAml = "incoming-aml", + IncomingConfirmation = "incoming-confirmation", + OutgoingKyc = "outgoing-kyc", +} ``` @@ -178,7 +218,7 @@ export type ScopeInfo = export type GetBalancesDetailOp = { op: WalletApiOperation.GetBalanceDetail; request: GetBalanceDetailRequest; - response: MerchantPaymentBalanceDetails; + response: PaymentBalanceDetails; }; // GetBalanceDetail = "getBalanceDetail" @@ -190,7 +230,7 @@ export interface GetBalanceDetailRequest { ``` ```typescript -export interface MerchantPaymentBalanceDetails { +export interface PaymentBalanceDetails { /** * Balance of type "available" (see balance.ts for definition). */ @@ -206,11 +246,18 @@ export interface MerchantPaymentBalanceDetails { /** * Balance of type "merchant-acceptable" (see balance.ts for definition). */ - balanceMerchantAcceptable: AmountJson; + balanceReceiverAcceptable: AmountJson; /** * Balance of type "merchant-depositable" (see balance.ts for definition). */ - balanceMerchantDepositable: AmountJson; + balanceReceiverDepositable: AmountJson; + /** + * Balance that's depositable with the exchange. + * This balance is reduced by the exchange's debit restrictions + * and wire fee configuration. + */ + balanceExchangeDepositable: AmountJson; + maxEffectiveSpendAmount: AmountJson; } ``` @@ -236,6 +283,108 @@ 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 +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 /** @@ -253,26 +402,80 @@ 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; /** + * Sort order of the transaction items. + * By default, items are sorted ascending by their + * main timestamp. + * + * ascending: ascending by timestamp, but pending transactions first + * descending: ascending by timestamp, but pending transactions first + * stable-ascending: ascending by timestamp, with pending transactions amidst other transactions + * (stable in the sense of: pending transactions don't jump around) + */ + sort?: "ascending" | "descending" | "stable-ascending"; + /** * If true, include all refreshes in the transactions list. */ includeRefreshes?: boolean; + filterByState?: TransactionStateFilter; } ``` + +### ListAssociatedRefreshesOp ```typescript -export interface TransactionsResponse { - transactions: Transaction[]; +/** + * 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 +/** + * Get sample transactions. + */ +export type TestingGetSampleTransactionsOp = { + op: WalletApiOperation.TestingGetSampleTransactions; + request: EmptyObject; + response: TransactionsResponse; +}; +// TestingGetSampleTransactions = "testingGetSampleTransactions" + +``` + ### GetTransactionByIdOp ```typescript export type GetTransactionByIdOp = { @@ -290,6 +493,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 = { @@ -316,7 +536,7 @@ export type DeleteTransactionOp = { ``` ```typescript export interface DeleteTransactionRequest { - transactionId: string; + transactionId: TransactionIdStr; } ``` @@ -336,7 +556,7 @@ export type RetryTransactionOp = { ``` ```typescript export interface RetryTransactionRequest { - transactionId: string; + transactionId: TransactionIdStr; } ``` @@ -357,6 +577,28 @@ export type AbortTransactionOp = { ``` +### FailTransactionOp +```typescript +/** + * Cancel aborting a transaction + * + * For payment transactions, it puts the payment into an "aborting" state. + */ +export type FailTransactionOp = { + op: WalletApiOperation.FailTransaction; + request: FailTransactionRequest; + response: EmptyObject; +}; +// FailTransaction = "failTransaction" + +``` +```typescript +export interface FailTransactionRequest { + transactionId: TransactionIdStr; +} + +``` + ### SuspendTransactionOp ```typescript /** @@ -393,7 +635,7 @@ export type ResumeTransactionOp = { export type GetWithdrawalDetailsForAmountOp = { op: WalletApiOperation.GetWithdrawalDetailsForAmount; request: GetWithdrawalDetailsForAmountRequest; - response: ManualWithdrawalDetails; + response: WithdrawalDetailsForAmount; }; // GetWithdrawalDetailsForAmount = "getWithdrawalDetailsForAmount" @@ -401,16 +643,18 @@ export type GetWithdrawalDetailsForAmountOp = { ```typescript export interface GetWithdrawalDetailsForAmountRequest { exchangeBaseUrl: string; - amount: string; + amount: AmountString; restrictAge?: number; } ``` ```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; /** @@ -422,14 +666,30 @@ 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. + * + * @deprecated in favor of withdrawalAccountsList */ paytoUris: string[]; /** + * Ways to pay the exchange, including accounts that require currency conversion. + */ + 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; } ``` @@ -451,17 +711,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 @@ -489,7 +761,7 @@ export interface AcceptBankIntegratedWithdrawalRequest { export interface AcceptWithdrawalResponse { reservePub: string; confirmTransferUrl?: string; - transactionId: string; + transactionId: TransactionIdStr; } ``` @@ -510,7 +782,7 @@ export type AcceptManualWithdrawalOp = { ```typescript export interface AcceptManualWithdrawalRequest { exchangeBaseUrl: string; - amount: string; + amount: AmountString; restrictAge?: number; } @@ -519,13 +791,16 @@ export interface AcceptManualWithdrawalRequest { export interface AcceptManualWithdrawalResult { /** * Payto URIs that can be used to fund the withdrawal. + * + * @deprecated in favor of withdrawalAccountsList */ exchangePaytoUris: string[]; /** * Public key of the newly created reserve. */ reservePub: string; - transactionId: string; + withdrawalAccountsList: WithdrawalExchangeAccountDetails[]; + transactionId: TransactionIdStr; } ``` @@ -550,6 +825,30 @@ export interface PreparePayRequest { ``` +### SharePaymentOp +```typescript +export type SharePaymentOp = { + op: WalletApiOperation.SharePayment; + request: SharePaymentRequest; + response: SharePaymentResult; +}; +// SharePayment = "sharePayment" + +``` +```typescript +export interface SharePaymentRequest { + merchantBaseUrl: string; + orderId: string; +} + +``` +```typescript +export interface SharePaymentResult { + privatePayUri: string; +} + +``` + ### PreparePayForTemplateOp ```typescript /** @@ -566,7 +865,7 @@ export type PreparePayForTemplateOp = { ```typescript export interface PreparePayTemplateRequest { talerPayTemplateUri: string; - templateParams: Record<string, string>; + templateParams?: TemplateParams; } ``` @@ -593,12 +892,6 @@ export interface GetContractTermsDetailsRequest { * processing in the wallet. */ export interface WalletContractData { - products?: Product[]; - summaryI18n: - | { - [lang_tag: string]: string; - } - | undefined; /** * Fulfillment URL, or the empty string if the order has no fulfillment URL. * @@ -615,27 +908,20 @@ export interface WalletContractData { orderId: string; merchantBaseUrl: string; summary: string; + summaryI18n: + | { + [lang_tag: string]: string; + } + | undefined; autoRefund: TalerProtocolDuration | undefined; - maxWireFee: AmountString; - wireFeeAmortization: number; payDeadline: TalerProtocolTimestamp; refundDeadline: TalerProtocolTimestamp; - allowedAuditors: AllowedAuditorInfo[]; allowedExchanges: AllowedExchangeInfo[]; timestamp: TalerProtocolTimestamp; wireMethod: string; wireInfoHash: string; maxDepositFee: AmountString; minimumAge?: number; - deliveryDate: TalerProtocolTimestamp | undefined; - deliveryLocation: Location | undefined; -} - -``` -```typescript -export interface AllowedAuditorInfo { - auditorBaseUrl: string; - auditorPub: string; } ``` @@ -663,7 +949,11 @@ export type ConfirmPayOp = { ``` ```typescript export interface ConfirmPayRequest { - proposalId: string; + /** + * @deprecated use transactionId instead + */ + proposalId?: string; + transactionId?: TransactionIdStr; sessionId?: string; forcedCoinSel?: ForcedCoinSel; } @@ -680,165 +970,179 @@ 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; } ``` -### ApplyRefundOp +### StartRefundQueryForUriOp ```typescript /** * Check for a refund based on a taler://refund URI. */ -export type ApplyRefundOp = { - op: WalletApiOperation.ApplyRefund; - request: ApplyRefundRequest; - response: ApplyRefundResponse; +export type StartRefundQueryForUriOp = { + op: WalletApiOperation.StartRefundQueryForUri; + request: PrepareRefundRequest; + response: StartRefundQueryForUriResponse; }; -// ApplyRefund = "applyRefund" +// StartRefundQueryForUri = "startRefundQueryForUri" ``` ```typescript -export interface ApplyRefundRequest { +export interface PrepareRefundRequest { talerRefundUri: string; } ``` +```typescript +export interface StartRefundQueryForUriResponse { + /** + * Transaction id of the *payment* where the refund query was started. + */ + transactionId: TransactionIdStr; +} + +``` -### ApplyRefundFromPurchaseIdOp +### StartRefundQueryOp ```typescript -export type ApplyRefundFromPurchaseIdOp = { - op: WalletApiOperation.ApplyRefundFromPurchaseId; - request: ApplyRefundFromPurchaseIdRequest; - response: ApplyRefundResponse; +export type StartRefundQueryOp = { + op: WalletApiOperation.StartRefundQuery; + request: StartRefundQueryRequest; + response: EmptyObject; }; -// ApplyRefundFromPurchaseId = "applyRefundFromPurchaseId" +// StartRefundQuery = "startRefundQuery" ``` ```typescript -export interface ApplyRefundFromPurchaseIdRequest { - purchaseId: string; +export interface StartRefundQueryRequest { + transactionId: TransactionIdStr; } ``` -### PrepareRefundOp +### ListGlobalCurrencyAuditorsOp ```typescript -export type PrepareRefundOp = { - op: WalletApiOperation.PrepareRefund; - request: PrepareRefundRequest; - response: PrepareRefundResult; +export type ListGlobalCurrencyAuditorsOp = { + op: WalletApiOperation.ListGlobalCurrencyAuditors; + request: EmptyObject; + response: ListGlobalCurrencyAuditorsResponse; }; -// PrepareRefund = "prepareRefund" +// ListGlobalCurrencyAuditors = "listGlobalCurrencyAuditors" ``` ```typescript -export interface PrepareRefundRequest { - talerRefundUri: string; +export interface ListGlobalCurrencyAuditorsResponse { + auditors: { + currency: string; + auditorBaseUrl: string; + auditorPub: string; + }[]; } ``` + +### ListGlobalCurrencyExchangesOp ```typescript -export interface PrepareRefundResult { - proposalId: string; - effectivePaid: AmountString; - gone: AmountString; - granted: AmountString; - pending: boolean; - awaiting: AmountString; - info: OrderShortInfo; +export type ListGlobalCurrencyExchangesOp = { + op: WalletApiOperation.ListGlobalCurrencyExchanges; + request: EmptyObject; + response: ListGlobalCurrencyExchangesResponse; +}; +// ListGlobalCurrencyExchanges = "listGlobalCurrencyExchanges" + +``` +```typescript +export interface ListGlobalCurrencyExchangesResponse { + exchanges: { + currency: string; + exchangeBaseUrl: string; + exchangeMasterPub: string; + }[]; } ``` -### PrepareTipOp +### AddGlobalCurrencyExchangeOp ```typescript -/** - * Query and store information about a tip. - */ -export type PrepareTipOp = { - op: WalletApiOperation.PrepareTip; - request: PrepareTipRequest; - response: PrepareTipResult; +export type AddGlobalCurrencyExchangeOp = { + op: WalletApiOperation.AddGlobalCurrencyExchange; + request: AddGlobalCurrencyExchangeRequest; + response: EmptyObject; }; -// PrepareTip = "prepareTip" +// AddGlobalCurrencyExchange = "addGlobalCurrencyExchange" ``` ```typescript -export interface PrepareTipRequest { - talerTipUri: string; +export interface AddGlobalCurrencyExchangeRequest { + currency: string; + exchangeBaseUrl: string; + exchangeMasterPub: string; } ``` + +### AddGlobalCurrencyAuditorOp ```typescript -export interface PrepareTipResult { - /** - * Unique ID for the tip assigned by the wallet. - * Typically different from the merchant-generated tip ID. - */ - walletTipId: string; - /** - * Has the tip already been accepted? - */ - accepted: boolean; - /** - * Amount that the merchant gave. - */ - tipAmountRaw: AmountString; - /** - * Amount that arrived at the wallet. - * Might be lower than the raw amount due to fees. - */ - tipAmountEffective: 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. - */ - exchangeBaseUrl: string; - /** - * Time when the tip will expire. After it expired, it can't be picked - * up anymore. - */ - expirationTimestamp: TalerProtocolTimestamp; +export type AddGlobalCurrencyAuditorOp = { + op: WalletApiOperation.AddGlobalCurrencyAuditor; + request: AddGlobalCurrencyAuditorRequest; + response: EmptyObject; +}; +// AddGlobalCurrencyAuditor = "addGlobalCurrencyAuditor" + +``` +```typescript +export interface AddGlobalCurrencyAuditorRequest { + currency: string; + auditorBaseUrl: string; + auditorPub: string; } ``` -### AcceptTipOp +### RemoveGlobalCurrencyExchangeOp ```typescript -/** - * Accept a tip. - */ -export type AcceptTipOp = { - op: WalletApiOperation.AcceptTip; - request: AcceptTipRequest; - response: AcceptTipResponse; +export type RemoveGlobalCurrencyExchangeOp = { + op: WalletApiOperation.RemoveGlobalCurrencyExchange; + request: RemoveGlobalCurrencyExchangeRequest; + response: EmptyObject; }; -// AcceptTip = "acceptTip" +// RemoveGlobalCurrencyExchange = "removeGlobalCurrencyExchange" ``` ```typescript -export interface AcceptTipRequest { - walletTipId: string; +export interface RemoveGlobalCurrencyExchangeRequest { + currency: string; + exchangeBaseUrl: string; + exchangeMasterPub: string; } ``` + +### RemoveGlobalCurrencyAuditorOp ```typescript -export interface AcceptTipResponse { - transactionId: string; - next_url?: string; +export type RemoveGlobalCurrencyAuditorOp = { + op: WalletApiOperation.RemoveGlobalCurrencyAuditor; + request: RemoveGlobalCurrencyAuditorRequest; + response: EmptyObject; +}; +// RemoveGlobalCurrencyAuditor = "removeGlobalCurrencyAuditor" + +``` +```typescript +export interface RemoveGlobalCurrencyAuditorRequest { + currency: string; + auditorBaseUrl: string; + auditorPub: string; } ``` @@ -863,6 +1167,78 @@ export interface ExchangesListResponse { ``` +### ListExchangesForScopedCurrencyOp +```typescript +/** + * List exchanges that are available for withdrawing a particular + * scoped currency. + */ +export type ListExchangesForScopedCurrencyOp = { + op: WalletApiOperation.ListExchangesForScopedCurrency; + request: ListExchangesForScopedCurrencyRequest; + response: ExchangesShortListResponse; +}; +// ListExchangesForScopedCurrency = "listExchangesForScopedCurrency" + +``` +```typescript +export interface ListExchangesForScopedCurrencyRequest { + scope: ScopeInfo; +} + +``` +```typescript +export interface ExchangesShortListResponse { + exchanges: ShortExchangeListItem[]; +} + +``` +```typescript +export interface ShortExchangeListItem { + exchangeBaseUrl: string; +} + +``` + +### 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 /** @@ -877,6 +1253,27 @@ export type AddExchangeOp = { ``` +### UpdateExchangeEntryOp +```typescript +/** + * Update an exchange entry. + */ +export type UpdateExchangeEntryOp = { + op: WalletApiOperation.UpdateExchangeEntry; + request: UpdateExchangeEntryRequest; + response: EmptyObject; +}; +// UpdateExchangeEntry = "updateExchangeEntry" + +``` +```typescript +export interface UpdateExchangeEntryRequest { + exchangeBaseUrl: string; + force?: boolean; +} + +``` + ### ListKnownBankAccountsOp ```typescript export type ListKnownBankAccountsOp = { @@ -924,7 +1321,7 @@ export interface PaytoUriUnknown extends PaytoUriGeneric { ``` ```typescript export interface PaytoUriGeneric { - targetType: string; + targetType: PaytoType | string; targetPath: string; params: { [name: string]: string; @@ -933,6 +1330,10 @@ export interface PaytoUriGeneric { ``` ```typescript +export type PaytoType = "iban" | "bitcoin" | "x-taler-bank"; + +``` +```typescript export interface PaytoUriIBAN extends PaytoUriGeneric { isKnown: true; targetType: "iban"; @@ -954,6 +1355,7 @@ export interface PaytoUriTalerBank extends PaytoUriGeneric { export interface PaytoUriBitcoin extends PaytoUriGeneric { isKnown: true; targetType: "bitcoin"; + address: string; segwitAddrs: Array<string>; } @@ -1008,11 +1410,18 @@ export type SetExchangeTosAcceptedOp = { // SetExchangeTosAccepted = "setExchangeTosAccepted" ``` + +### SetExchangeTosForgottenOp ```typescript -export interface AcceptExchangeTosRequest { - exchangeBaseUrl: string; - etag: string | undefined; -} +/** + * Accept a particular version of the exchange terms of service. + */ +export type SetExchangeTosForgottenOp = { + op: WalletApiOperation.SetExchangeTosForgotten; + request: AcceptExchangeTosRequest; + response: EmptyObject; +}; +// SetExchangeTosForgotten = "SetExchangeTosForgotten" ``` @@ -1033,6 +1442,7 @@ export type GetExchangeTosOp = { export interface GetExchangeTosRequest { exchangeBaseUrl: string; acceptedFormat?: string[]; + acceptLanguage?: string; } ``` @@ -1055,6 +1465,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; } @@ -1084,7 +1504,6 @@ export interface ExchangeFullDetails { exchangeBaseUrl: string; currency: string; paytoUris: string[]; - tos: ExchangeTosStatusDetails; auditors: ExchangeAuditor[]; wireInfo: WireInfo; denomFees: DenomOperationMap<FeeDescription[]>; @@ -1094,28 +1513,21 @@ export interface ExchangeFullDetails { ``` ```typescript -export interface ExchangeTosStatusDetails { - acceptedVersion?: string; - currentVersion?: string; - contentType?: string; - content?: string; -} - -``` -```typescript export interface WireInfo { feesForType: WireFeeMap; - accounts: ExchangeAccount[]; + accounts: ExchangeWireAccount[]; } ``` ```typescript -/** - * Information about one of the exchange's bank accounts. - */ -export interface ExchangeAccount { +export interface ExchangeWireAccount { payto_uri: string; - master_sig: string; + conversion_url?: string; + credit_restrictions: AccountRestriction[]; + debit_restrictions: AccountRestriction[]; + master_sig: EddsaSignatureString; + bank_label?: string; + priority?: number; } ``` @@ -1129,142 +1541,154 @@ 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; } ``` -### CreateDepositGroupOp +### GetExchangeResourcesOp ```typescript /** - * Create a new deposit group. - * - * Deposit groups are used to deposit multiple coins to a bank - * account, usually the wallet user's own bank account. + * Get resources associated with an exchange. */ -export type CreateDepositGroupOp = { - op: WalletApiOperation.CreateDepositGroup; - request: CreateDepositGroupRequest; - response: CreateDepositGroupResponse; +export type GetExchangeResourcesOp = { + op: WalletApiOperation.GetExchangeResources; + request: GetExchangeResourcesRequest; + response: GetExchangeResourcesResponse; }; -// CreateDepositGroup = "createDepositGroup" +// GetExchangeResources = "getExchangeResources" ``` ```typescript -export interface CreateDepositGroupRequest { - depositPaytoUri: string; - amount: AmountString; +export interface GetExchangeResourcesRequest { + exchangeBaseUrl: string; } ``` ```typescript -export interface CreateDepositGroupResponse { - depositGroupId: string; - transactionId: string; +export interface GetExchangeResourcesResponse { + hasResources: boolean; } ``` -### TrackDepositGroupOp +### DeleteExchangeOp ```typescript /** - * Track the status of a deposit group by querying the exchange. + * Get resources associated with an exchange. */ -export type TrackDepositGroupOp = { - op: WalletApiOperation.TrackDepositGroup; - request: TrackDepositGroupRequest; - response: TrackDepositGroupResponse; +export type DeleteExchangeOp = { + op: WalletApiOperation.GetExchangeResources; + request: DeleteExchangeRequest; + response: EmptyObject; }; -// TrackDepositGroup = "trackDepositGroup" +// GetExchangeResources = "getExchangeResources" ``` ```typescript -export interface TrackDepositGroupRequest { - depositGroupId: string; +export interface DeleteExchangeRequest { + exchangeBaseUrl: string; + purge?: boolean; } ``` + +### GetCurrencySpecificationOp ```typescript -export interface TrackDepositGroupResponse { - responses: TrackTransaction[]; -} +export type GetCurrencySpecificationOp = { + op: WalletApiOperation.GetCurrencySpecification; + request: GetCurrencySpecificationRequest; + response: GetCurrencySpecificationResponse; +}; +// GetCurrencySpecification = "getCurrencySpecification" ``` ```typescript -export type TrackTransaction = - | ({ - type: "accepted"; - } & TrackTransactionAccepted) - | ({ - type: "wired"; - } & TrackTransactionWired); +export interface GetCurrencySpecificationRequest { + scope: ScopeInfo; +} ``` ```typescript -interface TrackTransactionAccepted { - requirement_row?: number; - kyc_ok: boolean; - execution_time: TalerProtocolTimestamp; +export interface GetCurrencySpecificationResponse { + currencySpecification: CurrencySpecification; } ``` + +### GenerateDepositGroupTxIdOp ```typescript -export interface TrackTransactionWired { - wtid: Base32String; - execution_time: TalerProtocolTimestamp; - coin_contribution: AmountString; - exchange_sig: EddsaSignatureString; - exchange_pub: EddsaPublicKeyString; +/** + * Generate a fresh transaction ID for a deposit group. + * + * The resulting transaction ID can be specified when creating + * a deposit group, so that the client can already start waiting for notifications + * on that specific deposit group before the GreateDepositGroup request returns. + */ +export type GenerateDepositGroupTxIdOp = { + op: WalletApiOperation.GenerateDepositGroupTxId; + request: EmptyObject; + response: TxIdResponse; +}; +// GenerateDepositGroupTxId = "generateDepositGroupTxId" + +``` +```typescript +export interface TxIdResponse { + transactionId: TransactionIdStr; } ``` -### GetFeeForDepositOp +### CreateDepositGroupOp ```typescript -export type GetFeeForDepositOp = { - op: WalletApiOperation.GetFeeForDeposit; - request: GetFeeForDepositRequest; - response: DepositGroupFees; +/** + * Create a new deposit group. + * + * Deposit groups are used to deposit multiple coins to a bank + * account, usually the wallet user's own bank account. + */ +export type CreateDepositGroupOp = { + op: WalletApiOperation.CreateDepositGroup; + request: CreateDepositGroupRequest; + response: CreateDepositGroupResponse; }; -// GetFeeForDeposit = "getFeeForDeposit" +// CreateDepositGroup = "createDepositGroup" ``` ```typescript -export interface GetFeeForDepositRequest { +export interface CreateDepositGroupRequest { + /** + * Pre-allocated transaction ID. + * Allows clients to easily handle notifications + * that occur while the operation has been created but + * before the creation request has returned. + */ + transactionId?: TransactionIdStr; depositPaytoUri: string; amount: AmountString; } ``` ```typescript -export interface DepositGroupFees { - coin: AmountString; - wire: AmountString; - refresh: AmountString; +export interface CreateDepositGroupResponse { + depositGroupId: string; + transactionId: TransactionIdStr; } ``` @@ -1290,6 +1714,15 @@ export interface PrepareDepositRequest { export interface PrepareDepositResponse { totalDepositCost: AmountString; effectiveDepositAmount: AmountString; + fees: DepositGroupFees; +} + +``` +```typescript +export interface DepositGroupFees { + coin: AmountString; + wire: AmountString; + refresh: AmountString; } ``` @@ -1481,8 +1914,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; @@ -1589,17 +2022,73 @@ export interface SetWalletDeviceIdRequest { ``` -### ExportBackupPlainOp +### ListStoredBackupsOp ```typescript -/** - * Export a backup JSON, mostly useful for testing. - */ -export type ExportBackupPlainOp = { - op: WalletApiOperation.ExportBackupPlain; +export type ListStoredBackupsOp = { + op: WalletApiOperation.ListStoredBackups; + request: EmptyObject; + response: StoredBackupList; +}; +// ListStoredBackups = "listStoredBackups" + +``` +```typescript +export interface StoredBackupList { + storedBackups: { + name: string; + }[]; +} + +``` + +### CreateStoredBackupsOp +```typescript +export type CreateStoredBackupsOp = { + op: WalletApiOperation.CreateStoredBackup; request: EmptyObject; - response: WalletBackupContentV1; + response: CreateStoredBackupResponse; }; -// ExportBackupPlain = "exportBackupPlain" +// CreateStoredBackup = "createStoredBackup" + +``` +```typescript +export interface CreateStoredBackupResponse { + name: string; +} + +``` + +### RecoverStoredBackupsOp +```typescript +export type RecoverStoredBackupsOp = { + op: WalletApiOperation.RecoverStoredBackup; + request: RecoverStoredBackupRequest; + response: EmptyObject; +}; +// RecoverStoredBackup = "recoverStoredBackup" + +``` +```typescript +export interface RecoverStoredBackupRequest { + name: string; +} + +``` + +### DeleteStoredBackupOp +```typescript +export type DeleteStoredBackupOp = { + op: WalletApiOperation.DeleteStoredBackup; + request: DeleteStoredBackupRequest; + response: EmptyObject; +}; +// DeleteStoredBackup = "deleteStoredBackup" + +``` +```typescript +export interface DeleteStoredBackupRequest { + name: string; +} ``` @@ -1636,6 +2125,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; } ``` @@ -1647,27 +2147,26 @@ export interface CheckPeerPushDebitResponse { */ export type InitiatePeerPushDebitOp = { op: WalletApiOperation.InitiatePeerPushDebit; - request: InitiatePeerPushPaymentRequest; - response: InitiatePeerPushPaymentResponse; + request: InitiatePeerPushDebitRequest; + response: InitiatePeerPushDebitResponse; }; // InitiatePeerPushDebit = "initiatePeerPushDebit" ``` ```typescript -export interface InitiatePeerPushPaymentRequest { +export interface InitiatePeerPushDebitRequest { exchangeBaseUrl?: string; partialContractTerms: PeerContractTerms; } ``` ```typescript -export interface InitiatePeerPushPaymentResponse { +export interface InitiatePeerPushDebitResponse { exchangeBaseUrl: string; pursePub: string; mergePriv: string; contractPriv: string; - talerUri: string; - transactionId: string; + transactionId: TransactionIdStr; } ``` @@ -1679,22 +2178,33 @@ export interface InitiatePeerPushPaymentResponse { */ export type PreparePeerPushCreditOp = { op: WalletApiOperation.PreparePeerPushCredit; - request: PreparePeerPushCredit; + request: PreparePeerPushCreditRequest; response: PreparePeerPushCreditResponse; }; // PreparePeerPushCredit = "preparePeerPushCredit" ``` ```typescript +export interface PreparePeerPushCreditRequest { + talerUri: string; +} + +``` +```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; - peerPushPaymentIncomingId: string; } ``` @@ -1714,10 +2224,7 @@ export type ConfirmPeerPushCreditOp = { ``` ```typescript export interface ConfirmPeerPushCreditRequest { - /** - * Transparent identifier of the incoming peer push payment. - */ - peerPushPaymentIncomingId: string; + transactionId: string; } ``` @@ -1747,6 +2254,11 @@ export interface CheckPeerPullCreditResponse { exchangeBaseUrl: string; amountRaw: AmountString; amountEffective: AmountString; + /** + * Number of coins that will be used, + * can be used by the UI to warn if excessively large. + */ + numCoins: number; } ``` @@ -1776,9 +2288,11 @@ export interface InitiatePeerPullCreditResponse { /** * Taler URI for the other party to make the payment * that was requested. + * + * @deprecated since it's not necessarily valid yet until the tx is in the right state */ talerUri: string; - transactionId: string; + transactionId: TransactionIdStr; } ``` @@ -1811,7 +2325,8 @@ export interface PreparePeerPullDebitResponse { amount: AmountString; amountRaw: AmountString; amountEffective: AmountString; - peerPullPaymentIncomingId: string; + peerPullDebitId: string; + transactionId: TransactionIdStr; } ``` @@ -1831,10 +2346,30 @@ export type ConfirmPeerPullDebitOp = { ``` ```typescript export interface ConfirmPeerPullDebitRequest { - /** - * Transparent identifier of the incoming peer pull payment. - */ - peerPullPaymentIncomingId: string; + transactionId: TransactionIdStr; +} + +``` + +### ValidateIbanOp +```typescript +export type ValidateIbanOp = { + op: WalletApiOperation.ValidateIban; + request: ValidateIbanRequest; + response: ValidateIbanResponse; +}; +// ValidateIban = "validateIban" + +``` +```typescript +export interface ValidateIbanRequest { + iban: string; +} + +``` +```typescript +export interface ValidateIbanResponse { + valid: boolean; } ``` @@ -1857,12 +2392,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 @@ -1915,23 +2456,6 @@ export interface ApplyDevExperimentRequest { ``` -### SetDevModeOp -```typescript -export type SetDevModeOp = { - op: WalletApiOperation.SetDevMode; - request: SetDevModeRequest; - response: EmptyObject; -}; -// SetDevMode = "setDevMode" - -``` -```typescript -export interface SetDevModeRequest { - devModeEnabled: boolean; -} - -``` - ### RunIntegrationTestOp ```typescript /** @@ -1946,16 +2470,19 @@ export type RunIntegrationTestOp = { // RunIntegrationTest = "runIntegrationTest" ``` + +### RunIntegrationTestV2Op ```typescript -export interface IntegrationTestArgs { - exchangeBaseUrl: string; - bankBaseUrl: string; - bankAccessApiBaseUrl?: string; - merchantBaseUrl: string; - merchantAuthToken?: string; - amountToWithdraw: string; - amountToSpend: string; -} +/** + * Run a simple integration test on a test deployment + * of the exchange and merchant. + */ +export type RunIntegrationTestV2Op = { + op: WalletApiOperation.RunIntegrationTestV2; + request: IntegrationTestArgs; + response: EmptyObject; +}; +// RunIntegrationTestV2 = "runIntegrationTestV2" ``` @@ -1989,12 +2516,11 @@ export type WithdrawTestBalanceOp = { ``` ```typescript export interface WithdrawTestBalanceRequest { - amount: string; - bankBaseUrl: string; + amount: AmountString; /** - * Bank access API base URL. Defaults to the bankBaseUrl. + * Corebank API base URL. */ - bankAccessApiBaseUrl?: string; + corebankApiBaseUrl: string; exchangeBaseUrl: string; forcedDenomSel?: ForcedDenomSel; } @@ -2033,7 +2559,7 @@ export type TestPayOp = { export interface TestPayArgs { merchantBaseUrl: string; merchantAuthToken?: string; - amount: string; + amount: AmountString; summary: string; forcedCoinSel?: ForcedCoinSel; } @@ -2041,60 +2567,10 @@ export interface TestPayArgs { ``` ```typescript export interface TestPayResult { - payCoinSelection: PayCoinSelection; -} - -``` -```typescript -/** - * Result of selecting coins, contains the exchange, and selected - * coins with their denomination. - */ -export interface PayCoinSelection { - /** - * Amount requested by the merchant. - */ - paymentAmount: AmountString; - /** - * Public keys of the coins that were selected. - */ - coinPubs: string[]; /** - * Amount that each coin contributes. + * Number of coins used for the payment. */ - coinContributions: AmountString[]; - /** - * How much of the wire fees is the customer paying? - */ - customerWireFees: AmountString; - /** - * How much of the deposit fees is the customer paying? - */ - customerDepositFees: AmountString; -} - -``` - -### WithdrawFakebankOp -```typescript -/** - * Make a withdrawal from a fakebank, i.e. - * a bank where test users can be registered freely - * and testing APIs are available. - */ -export type WithdrawFakebankOp = { - op: WalletApiOperation.WithdrawFakebank; - request: WithdrawFakebankRequest; - response: EmptyObject; -}; -// WithdrawFakebank = "withdrawFakebank" - -``` -```typescript -export interface WithdrawFakebankRequest { - amount: AmountString; - exchange: string; - bank: string; + numCoins: number; } ``` @@ -2103,344 +2579,26 @@ export interface WithdrawFakebankRequest { ```typescript /** * Get wallet-internal pending tasks. + * + * @deprecated */ export type GetPendingTasksOp = { op: WalletApiOperation.GetPendingOperations; request: EmptyObject; - response: PendingTasksResponse; + response: any; }; // GetPendingOperations = "getPendingOperations" ``` -```typescript -/** - * Response returned from the pending operations API. - */ -export interface PendingOperationsResponse { - /** - * List of pending operations. - */ - pendingOperations: PendingTaskInfo[]; -} - -``` -```typescript -/** - * Information about a pending operation. - */ -export type PendingTaskInfo = PendingTaskInfoCommon & - ( - | PendingExchangeUpdateTask - | PendingExchangeCheckRefreshTask - | PendingPurchaseTask - | PendingRefreshTask - | PendingTipPickupTask - | PendingWithdrawTask - | PendingRecoupTask - | PendingDepositTask - | PendingBackupTask - | PendingPeerPushInitiationTask - | PendingPeerPullInitiationTask - | PendingPeerPullDebitTask - | PendingPeerPushCreditTask - ); - -``` -```typescript -/** - * Fields that are present in every pending operation. - */ -export interface PendingTaskInfoCommon { - /** - * Type of the pending operation. - */ - type: PendingTaskType; - /** - * Unique identifier for the pending task. - */ - id: string; - /** - * 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. - */ - givesLifeness: boolean; - /** - * Operation is active and waiting for a longpoll result. - */ - isLongpolling: boolean; - /** - * Operation is waiting to be executed. - */ - isDue: boolean; - /** - * Timestamp when the pending operation should be executed next. - */ - timestampDue: AbsoluteTime; - /** - * Retry info. Currently used to stop the wallet after any operation - * exceeds a number of retries. - */ - retryInfo?: RetryInfo; -} - -``` -```typescript -export enum PendingTaskType { - ExchangeUpdate = "exchange-update", - ExchangeCheckRefresh = "exchange-check-refresh", - Purchase = "purchase", - Refresh = "refresh", - Recoup = "recoup", - TipPickup = "tip-pickup", - Withdraw = "withdraw", - Deposit = "deposit", - Backup = "backup", - // FIXME: Rename to peer-push-debit and peer-pull-debit - PeerPushInitiation = "peer-push-initiation", - PeerPullInitiation = "peer-pull-initiation", - PeerPushCredit = "peer-push-credit", - PeerPullDebit = "peer-pull-debit", -} - -``` -```typescript -export interface RetryInfo { - firstTry: AbsoluteTime; - nextRetry: AbsoluteTime; - retryCounter: number; -} - -``` -```typescript -export interface RetryPolicy { - readonly backoffDelta: Duration; - readonly backoffBase: number; - readonly maxTimeout: Duration; -} - -``` -```typescript -// Declare "static" methods in Error -interface ErrorConstructor { - /** Create .stack property on a target object */ - captureStackTrace(targetObject: object, constructorOpt?: Function): void; - /** - * Optional override for formatting stack traces - * - * @see https://v8.dev/docs/stack-trace-api#customizing-stack-traces - */ - prepareStackTrace?: - | ((err: Error, stackTraces: NodeJS.CallSite[]) => any) - | undefined; - stackTraceLimit: number; -} -``` +### GetActiveTasksOp ```typescript -interface CallSite { - /** - * Value of "this" - */ - getThis(): unknown; - /** - * Type of "this" as a string. - * This is the name of the function stored in the constructor field of - * "this", if available. Otherwise the object's [[Class]] internal - * property. - */ - getTypeName(): string | null; - /** - * Current function - */ - getFunction(): Function | undefined; - /** - * Name of the current function, typically its name property. - * If a name property is not available an attempt will be made to try - * to infer a name from the function's context. - */ - getFunctionName(): string | null; - /** - * Name of the property [of "this" or one of its prototypes] that holds - * the current function - */ - getMethodName(): string | null; - /** - * Name of the script [if this function was defined in a script] - */ - getFileName(): string | null; - /** - * Current line number [if this function was defined in a script] - */ - getLineNumber(): number | null; - /** - * Current column number [if this function was defined in a script] - */ - getColumnNumber(): number | null; - /** - * A call site object representing the location where eval was called - * [if this function was created using a call to eval] - */ - getEvalOrigin(): string | undefined; - /** - * Is this a toplevel invocation, that is, is "this" the global object? - */ - isToplevel(): boolean; - /** - * Does this call take place in code defined by a call to eval? - */ - isEval(): boolean; - /** - * Is this call in native V8 code? - */ - isNative(): boolean; - /** - * Is this a constructor call? - */ - isConstructor(): boolean; -} - -``` -```typescript -/** - * The wallet is currently updating information about an exchange. - */ -export interface PendingExchangeUpdateTask { - type: PendingTaskType.ExchangeUpdate; - exchangeBaseUrl: string; - lastError: TalerErrorDetail | undefined; -} - -``` -```typescript -/** - * The wallet should check whether coins from this exchange - * need to be auto-refreshed. - */ -export interface PendingExchangeCheckRefreshTask { - type: PendingTaskType.ExchangeCheckRefresh; - exchangeBaseUrl: string; -} - -``` -```typescript -/** - * A purchase needs to be processed (i.e. for download / payment / refund). - */ -export interface PendingPurchaseTask { - type: PendingTaskType.Purchase; - proposalId: string; - retryInfo?: RetryInfo; - /** - * Status of the payment as string, used only for debugging. - */ - statusStr: string; - lastError: TalerErrorDetail | undefined; -} - -``` -```typescript -/** - * Status of an ongoing withdrawal operation. - */ -export interface PendingRefreshTask { - type: PendingTaskType.Refresh; - lastError?: TalerErrorDetail; - refreshGroupId: string; - finishedPerCoin: boolean[]; - retryInfo?: RetryInfo; -} - -``` -```typescript -/** - * The wallet is picking up a tip that the user has accepted. - */ -export interface PendingTipPickupTask { - type: PendingTaskType.TipPickup; - tipId: string; - merchantBaseUrl: string; - merchantTipId: string; -} - -``` -```typescript -/** - * Status of an ongoing withdrawal operation. - */ -export interface PendingWithdrawTask { - type: PendingTaskType.Withdraw; - lastError: TalerErrorDetail | undefined; - retryInfo?: RetryInfo; - withdrawalGroupId: string; -} - -``` -```typescript -export interface PendingRecoupTask { - type: PendingTaskType.Recoup; - recoupGroupId: string; - retryInfo?: RetryInfo; - lastError: TalerErrorDetail | undefined; -} - -``` -```typescript -/** - * Status of an ongoing deposit operation. - */ -export interface PendingDepositTask { - type: PendingTaskType.Deposit; - lastError: TalerErrorDetail | undefined; - retryInfo: RetryInfo | undefined; - depositGroupId: string; -} - -``` -```typescript -export interface PendingBackupTask { - type: PendingTaskType.Backup; - backupProviderBaseUrl: string; - lastError: TalerErrorDetail | undefined; -} - -``` -```typescript -/** - * The wallet wants to send a peer push payment. - */ -export interface PendingPeerPushInitiationTask { - type: PendingTaskType.PeerPushInitiation; - pursePub: string; -} - -``` -```typescript -/** - * The wallet wants to send a peer pull payment. - */ -export interface PendingPeerPullInitiationTask { - type: PendingTaskType.PeerPullInitiation; - pursePub: string; -} - -``` -```typescript -/** - * The wallet wants to send a peer pull payment. - */ -export interface PendingPeerPullDebitTask { - type: PendingTaskType.PeerPullDebit; - peerPullPaymentIncomingId: string; -} - -``` -```typescript -/** - */ -export interface PendingPeerPushCreditTask { - type: PendingTaskType.PeerPushCredit; - peerPushPaymentIncomingId: string; -} +export type GetActiveTasksOp = { + op: WalletApiOperation.GetActiveTasks; + request: EmptyObject; + response: GetActiveTasks; +}; +// GetActiveTasks = "getActiveTasks" ``` @@ -2498,7 +2656,7 @@ export interface CoinDumpJson { spend_allocation: | { id: string; - amount: string; + amount: AmountString; } | undefined; /** @@ -2539,6 +2697,10 @@ export declare enum CoinStatus { */ Fresh = "fresh", /** + * Coin was lost as the denomination is not usable anymore. + */ + DenomLoss = "denom-loss", + /** * Fresh, but currently marked as "suspended", thus won't be used * for spending. Used for testing. */ @@ -2597,6 +2759,140 @@ export type Edx25519PrivateKeyEnc = FlavorP< ``` +### TestingSetTimetravelOp +```typescript +/** + * Add an offset to the wallet's internal time. + */ +export type TestingSetTimetravelOp = { + op: WalletApiOperation.TestingSetTimetravel; + request: TestingSetTimetravelRequest; + response: EmptyObject; +}; +// TestingSetTimetravel = "testingSetTimetravel" + +``` +```typescript +export interface TestingSetTimetravelRequest { + offsetMs: number; +} + +``` + +### TestingListTasksForTransactionOp +```typescript +/** + * Add an offset to the wallet's internal time. + */ +export type TestingListTasksForTransactionOp = { + op: WalletApiOperation.TestingListTaskForTransaction; + request: TestingListTasksForTransactionRequest; + response: TestingListTasksForTransactionsResponse; +}; +// TestingListTaskForTransaction = "testingListTasksForTransaction" + +``` +```typescript +export interface TestingListTasksForTransactionRequest { + transactionId: TransactionIdStr; +} + +``` +```typescript +export interface TestingListTasksForTransactionsResponse { + taskIdList: string[]; +} + +``` + +### TestingWaitTransactionsFinalOp +```typescript +/** + * Wait until all transactions are in a final state. + */ +export type TestingWaitTransactionsFinalOp = { + op: WalletApiOperation.TestingWaitTransactionsFinal; + request: EmptyObject; + response: EmptyObject; +}; +// TestingWaitTransactionsFinal = "testingWaitTransactionsFinal" + +``` + +### TestingWaitRefreshesFinalOp +```typescript +/** + * Wait until all refresh transactions are in a final state. + */ +export type TestingWaitRefreshesFinalOp = { + op: WalletApiOperation.TestingWaitRefreshesFinal; + request: EmptyObject; + response: EmptyObject; +}; +// TestingWaitRefreshesFinal = "testingWaitRefreshesFinal" + +``` + +### TestingWaitTransactionStateOp +```typescript +/** + * Wait until a transaction is in a particular state. + */ +export type TestingWaitTransactionStateOp = { + op: WalletApiOperation.TestingWaitTransactionState; + request: TestingWaitTransactionRequest; + response: EmptyObject; +}; +// TestingWaitTransactionState = "testingWaitTransactionState" + +``` +```typescript +export interface TestingWaitTransactionRequest { + transactionId: TransactionIdStr; + txState: TransactionState; +} + +``` + +### TestingPingOp +```typescript +export type TestingPingOp = { + op: WalletApiOperation.TestingPing; + request: EmptyObject; + response: EmptyObject; +}; +// TestingPing = "testingPing" + +``` + +### TestingGetDenomStatsOp +```typescript +/** + * Get stats about an exchange denomination. + */ +export type TestingGetDenomStatsOp = { + op: WalletApiOperation.TestingGetDenomStats; + request: TestingGetDenomStatsRequest; + response: TestingGetDenomStatsResponse; +}; +// TestingGetDenomStats = "testingGetDenomStats" + +``` +```typescript +export interface TestingGetDenomStatsRequest { + exchangeBaseUrl: string; +} + +``` +```typescript +export interface TestingGetDenomStatsResponse { + numKnown: number; + numOffered: number; + numLost: number; +} + +``` + ### SetCoinSuspendedOp ```typescript /** @@ -2635,36 +2931,166 @@ export type ForceRefreshOp = { ``` ```typescript export interface ForceRefreshRequest { - coinPubList: string[]; + refreshCoinSpecs: RefreshCoinSpec[]; +} + +``` +```typescript +export interface RefreshCoinSpec { + coinPub: string; + amount?: AmountString; } ``` ## Common Declarations ```typescript +export interface InitRequest { + config?: PartialWalletRunConfig; +} +``` +```typescript +export interface PartialWalletRunConfig { + builtin?: Partial<WalletRunConfig["builtin"]>; + testing?: Partial<WalletRunConfig["testing"]>; + features?: Partial<WalletRunConfig["features"]>; +} +``` +```typescript +export interface WalletRunConfig { + /** + * Initialization values useful for a complete startup. + * + * These are values may be overridden by different wallets + */ + builtin: { + exchanges: BuiltinExchange[]; + }; + /** + * Unsafe options which it should only be used to create + * testing environment. + */ + testing: { + /** + * Allow withdrawal of denominations even though they are about to expire. + */ + denomselAllowLate: boolean; + devModeActive: boolean; + insecureTrustExchange: boolean; + preventThrottling: boolean; + skipDefaults: boolean; + emitObservabilityEvents?: boolean; + }; + /** + * Configurations values that may be safe to show to the user + */ + features: { + allowHttp: boolean; + }; +} +``` +```typescript +export interface BuiltinExchange { + exchangeBaseUrl: string; + currencyHint: string; +} +``` +```typescript +export interface InitResponse { + versionInfo: WalletCoreVersion; +} +``` +```typescript export interface WalletCoreVersion { - hash: string | undefined; + implementationSemver: string; + implementationGitHash: string; + /** + * Wallet-core protocol version supported by this implementation + * of the API ("server" version). + */ 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; } ``` ```typescript +export type ScopeInfo = ScopeInfoGlobal | ScopeInfoExchange | ScopeInfoAuditor; +``` +```typescript +export type AmountString = string & { + [__amount_str]: true; +}; +``` +```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 +export interface ConvertAmountRequest { + amount: AmountString; + type: TransactionAmountMode; +} +``` +```typescript +export interface AmountResponse { + effectiveAmount: AmountString; + rawAmount: AmountString; +} +``` +```typescript +export interface GetAmountRequest { + currency: string; +} +``` +```typescript +export interface TransactionsResponse { + transactions: Transaction[]; +} +``` +```typescript export type Transaction = | TransactionWithdrawal | TransactionPayment | TransactionRefund - | TransactionTip + | TransactionReward | TransactionRefresh | TransactionDeposit | TransactionPeerPullCredit | TransactionPeerPullDebit | TransactionPeerPushCredit - | TransactionPeerPushDebit; + | TransactionPeerPushDebit + | TransactionInternalWithdrawal + | TransactionRecoup + | TransactionDenomLoss; ``` ```typescript +/** + * A withdrawal transaction (either bank-integrated or manual). + */ export interface TransactionWithdrawal extends TransactionCommon { type: TransactionType.Withdrawal; /** @@ -2686,23 +3112,15 @@ export interface TransactionWithdrawal extends TransactionCommon { export interface TransactionCommon { transactionId: TransactionIdStr; type: TransactionType; - timestamp: TalerProtocolTimestamp; - extendedStatus: ExtendedStatus; + timestamp: TalerPreciseTimestamp; /** - * 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 + * Transaction state, as per DD37. */ - pending: boolean; + txState: TransactionState; /** - * 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: TransactionAction[]; /** * Raw amount of the transaction (exclusive of fees or other extra costs). */ @@ -2712,35 +3130,129 @@ 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", - Tip = "tip", + Reward = "reward", Deposit = "deposit", PeerPushDebit = "peer-push-debit", PeerPushCredit = "peer-push-credit", PeerPullDebit = "peer-pull-debit", PeerPullCredit = "peer-pull-credit", + Recoup = "recoup", + DenomLoss = "denom-loss", +} +``` +```typescript +/** + * Precise timestamp, typically used in the wallet-core + * API but not in other Taler APIs so far. + */ +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 +export interface TransactionState { + major: TransactionMajorState; + minor?: TransactionMinorState; } ``` ```typescript -export declare enum ExtendedStatus { +export declare enum TransactionMajorState { + None = "none", Pending = "pending", Done = "done", Aborting = "aborting", Aborted = "aborted", + Suspended = "suspended", + Dialog = "dialog", + SuspendedAborting = "suspended-aborting", Failed = "failed", - KycRequired = "kyc-required", + Expired = "expired", + Deleted = "deleted", +} +``` +```typescript +export declare enum TransactionMinorState { + Unknown = "unknown", + Deposit = "deposit", + KycRequired = "kyc", + AmlRequired = "aml", + MergeKycRequired = "merge-kyc", + Track = "track", + SubmitPayment = "submit-payment", + RebindSession = "rebind-session", + Refresh = "refresh", + Pickup = "pickup", + AutoRefund = "auto-refund", + User = "user", + Bank = "bank", + Exchange = "exchange", + ClaimProposal = "claim-proposal", + CheckRefund = "check-refund", + CreatePurse = "create-purse", + DeletePurse = "delete-purse", + RefreshExpired = "refresh-expired", + Ready = "ready", + Merge = "merge", + Repurchase = "repurchase", + BankRegisterReserve = "bank-register-reserve", + BankConfirmTransfer = "bank-confirm-transfer", + WithdrawCoins = "withdraw-coins", + ExchangeWaitReserve = "exchange-wait-reserve", + AbortingBank = "aborting-bank", + Aborting = "aborting", + Refused = "refused", + Withdraw = "withdraw", + MerchantOrderProposed = "merchant-order-proposed", + Proposed = "proposed", + RefundAvailable = "refund-available", + AcceptRefund = "accept-refund", + PaidByOther = "paid-by-other", +} +``` +```typescript +export declare enum TransactionAction { + Delete = "delete", + Suspend = "suspend", + Resume = "resume", + Abort = "abort", + Fail = "fail", + Retry = "retry", } ``` ```typescript @@ -2757,6 +3269,8 @@ export interface AbsoluteTime { * Timestamp in milliseconds. */ readonly t_ms: number | "never"; + readonly _flavor?: typeof flavor_AbsoluteTime; + [opaque_AbsoluteTime]: true; } ``` ```typescript @@ -2784,8 +3298,11 @@ interface WithdrawalDetailsForManualTransfer { * Payto URIs that the exchange supports. * * Already contains the amount and message. + * + * @deprecated in favor of exchangeCreditAccounts */ exchangePaytoUris: string[]; + exchangeCreditAccountDetails?: WithdrawalExchangeAccountDetails[]; reservePub: string; /** * Is the reserve ready for withdrawal? @@ -2794,6 +3311,88 @@ interface WithdrawalDetailsForManualTransfer { } ``` ```typescript +export interface WithdrawalExchangeAccountDetails { + /** + * Payto URI to credit the exchange. + * + * Depending on whether the (manual!) withdrawal is accepted or just + * being checked, this already includes the subject with the + * reserve public key. + */ + 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. + * + * Absent if this is a conversion account and the conversion failed. + */ + transferAmount?: AmountString; + /** + * Currency specification for the external currency. + * + * Only included if this account requires a currency conversion. + */ + currencySpecification?: CurrencySpecification; + /** + * Further restrictions for sending money to the + * exchange. + */ + creditRestrictions?: AccountRestriction[]; + /** + * Label given to the account or the account's bank by the exchange. + */ + bankLabel?: string; + priority?: number; + /** + * 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 +export type AccountRestriction = + | RegexAccountRestriction + | DenyAllAccountRestriction; +``` +```typescript +export interface RegexAccountRestriction { + type: "regex"; + payto_regex: string; + human_hint: string; + human_hint_i18n?: InternationalizedString; +} +``` +```typescript +export interface InternationalizedString { + [lang_tag: string]: string; +} +``` +```typescript +export interface DenyAllAccountRestriction { + type: "deny"; +} +``` +```typescript interface WithdrawalDetailsForTalerBankIntegrationApi { type: WithdrawalType.TalerBankIntegrationApi; /** @@ -2812,6 +3411,7 @@ interface WithdrawalDetailsForTalerBankIntegrationApi { * Is the reserve ready for withdrawal? */ reserveIsReady: boolean; + exchangeCreditAccountDetails?: WithdrawalExchangeAccountDetails[]; } ``` ```typescript @@ -2826,12 +3426,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; @@ -2859,6 +3453,10 @@ export interface TransactionPayment extends TransactionCommon { * Is the wallet currently checking for a refund? */ refundQueryActive: boolean; + /** + * Does this purchase has an pos validation + */ + posConfirmation: string | undefined; } ``` ```typescript @@ -2884,19 +3482,6 @@ export interface OrderShortInfo { */ summary_i18n?: InternationalizedString; /** - * List of products that are part of the order - */ - products: Product[] | undefined; - /** - * Time indicating when the order should be delivered. - * May be overwritten by individual products. - */ - delivery_date?: TalerProtocolTimestamp; - /** - * Delivery location for (all!) products. - */ - delivery_location?: Location; - /** * URL of the fulfillment, given by the merchant */ fulfillmentUrl?: string; @@ -2914,11 +3499,11 @@ export interface OrderShortInfo { ```typescript export interface MerchantInfo { name: string; - jurisdiction?: Location; - address?: Location; - logo?: string; - website?: string; email?: string; + website?: string; + logo?: ImageDataUrl; + address?: Location; + jurisdiction?: Location; } ``` ```typescript @@ -2936,53 +3521,6 @@ export interface Location { } ``` ```typescript -export interface InternationalizedString { - [lang_tag: string]: string; -} -``` -```typescript -export interface Product { - product_id?: string; - description: string; - description_i18n?: { - [lang_tag: string]: string; - }; - quantity?: number; - unit?: string; - price?: AmountString; - image?: string; - taxes?: Tax[]; - delivery_date?: TalerProtocolTimestamp; -} -``` -```typescript -export interface Tax { - name: string; - tax: AmountString; -} -``` -```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; @@ -2993,19 +3531,28 @@ export interface RefundInfoShort { ```typescript export interface TransactionRefund extends TransactionCommon { type: TransactionType.Refund; + amountRaw: AmountString; + amountEffective: AmountString; refundedTransactionId: string; - info: OrderShortInfo; + paymentInfo: RefundPaymentInfo | undefined; +} +``` +```typescript +/** + * Summary information about the payment that we got a refund for. + */ +export interface RefundPaymentInfo { + summary: string; + summary_i18n?: InternationalizedString; /** - * Amount pending to be picked up + * More information about the merchant */ - refundPending: AmountString | undefined; - amountRaw: AmountString; - amountEffective: AmountString; + merchant: MerchantInfo; } ``` ```typescript -export interface TransactionTip extends TransactionCommon { - type: TransactionType.Tip; +export interface TransactionReward extends TransactionCommon { + type: TransactionType.Reward; amountRaw: AmountString; /** * More information about the merchant @@ -3056,6 +3603,9 @@ export declare enum RefreshReason { PayPeerPull = "pay-peer-pull", Refund = "refund", AbortPay = "abort-pay", + AbortDeposit = "abort-deposit", + AbortPeerPushDebit = "abort-peer-push-debit", + AbortPeerPullDebit = "abort-peer-pull-debit", Recoup = "recoup", BackupRestored = "backup-restored", Scheduled = "scheduled", @@ -3087,6 +3637,15 @@ export interface TransactionDeposit extends TransactionCommon { * Did all the deposit requests succeed? */ deposited: boolean; + trackingState: Array<DepositTransactionTrackingState>; +} +``` +```typescript +export interface DepositTransactionTrackingState { + wireTransferId: string; + timestampExecuted: TalerProtocolTimestamp; + amountRaw: AmountString; + wireFee: AmountString; } ``` ```typescript @@ -3110,8 +3669,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 @@ -3177,36 +3738,99 @@ export interface TransactionPeerPushDebit extends TransactionCommon { amountEffective: AmountString; /** * URI to accept the payment. + * + * Only present if the transaction is in a state where the other party can + * accept the payment. */ - talerUri: string; + talerUri?: string; } ``` ```typescript -export interface AbortTransactionRequest { - transactionId: string; +/** + * 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; /** - * Move the payment immediately into an aborted state. - * The UI should warn the user that this might lead - * to money being lost. - * - * Defaults to false. + * Exchange of the withdrawal. + */ + exchangeBaseUrl: string; + /** + * Amount that got subtracted from the reserve balance. */ - forceImmediateAbort?: boolean; + amountRaw: AmountString; + /** + * Amount that actually was (or will be) added to the wallet's balance. + */ + amountEffective: AmountString; + withdrawalDetails: WithdrawalDetails; +} +``` +```typescript +/** + * The exchange revoked a key and the wallet recoups funds. + */ +export interface TransactionRecoup extends TransactionCommon { + type: TransactionType.Recoup; } ``` ```typescript +/** + * A transaction to indicate financial loss due to denominations + * that became unusable for deposits. + */ +export interface TransactionDenomLoss extends TransactionCommon { + type: TransactionType.DenomLoss; + lossEventType: DenomLossEventType; + exchangeBaseUrl: string; +} +``` +```typescript +export declare enum DenomLossEventType { + DenomExpired = "denom-expired", + DenomVanished = "denom-vanished", + DenomUnoffered = "denom-unoffered", +} +``` +```typescript +export interface AbortTransactionRequest { + transactionId: TransactionIdStr; +} +``` +```typescript +/** + * Info about an exchange entry in the wallet. + */ export interface ExchangeListItem { exchangeBaseUrl: string; - currency: string | undefined; + masterPub: string | undefined; + currency: string; paytoUris: string[]; tosStatus: ExchangeTosStatus; - exchangeStatus: ExchangeEntryStatus; + exchangeEntryStatus: ExchangeEntryStatus; + exchangeUpdateStatus: ExchangeUpdateStatus; ageRestrictionOptions: number[]; /** - * Permanently added to the wallet, as opposed to just - * temporarily queried. + * P2P payments are disabled with this exchange + * (e.g. because no global fees are configured). */ - permanent: boolean; + peerPaymentsDisabled: boolean; + /** + * Set to true if this exchange doesn't charge any fees. + */ + noFees: boolean; + scopeInfo: ScopeInfo; + lastUpdateTimestamp: TalerPreciseTimestamp | undefined; /** * Information about the last error that occurred when trying * to update the exchange info. @@ -3216,18 +3840,26 @@ export interface ExchangeListItem { ``` ```typescript export declare enum ExchangeTosStatus { - New = "new", + Pending = "pending", + Proposed = "proposed", Accepted = "accepted", - Changed = "changed", - NotFound = "not-found", - Unknown = "unknown", } ``` ```typescript export declare enum ExchangeEntryStatus { - Unknown = "unknown", - Outdated = "outdated", - Ok = "ok", + Preset = "preset", + Ephemeral = "ephemeral", + Used = "used", +} +``` +```typescript +export declare enum ExchangeUpdateStatus { + Initial = "initial", + InitialUpdate = "initial-update", + Suspended = "suspended", + UnavailableUpdate = "unavailable-update", + Ready = "ready", + ReadyUpdate = "ready-update", } ``` ```typescript @@ -3255,12 +3887,15 @@ export type PreparePayResult = ```typescript export interface PreparePayResultInsufficientBalance { status: PreparePayResultType.InsufficientBalance; + transactionId: TransactionIdStr; + /** + * @deprecated use transactionId + */ proposalId: string; contractTerms: MerchantContractTerms; - amountRaw: string; - noncePriv: string; + amountRaw: AmountString; talerUri: string; - balanceDetails: PayMerchantInsufficientBalanceDetails; + balanceDetails: PaymentInsufficientBalanceDetails; } ``` ```typescript @@ -3269,135 +3904,32 @@ export interface PreparePayResultInsufficientBalance { * FIXME: Add type field! */ export interface MerchantContractTerms { - /** - * Hash of the merchant's wire details. - */ h_wire: string; - /** - * Hash of the merchant's wire details. - */ auto_refund?: TalerProtocolDuration; - /** - * Wire method the merchant wants to use. - */ wire_method: string; - /** - * Human-readable short summary of the contract. - */ summary: string; summary_i18n?: InternationalizedString; - /** - * Nonce used to ensure freshness. - */ - nonce: string; - /** - * Total amount payable. - */ + order_id: string; amount: string; - /** - * Auditors accepted by the merchant. - */ - auditors: AuditorHandle[]; - /** - * Deadline to pay for the contract. - */ + nonce: string; pay_deadline: TalerProtocolTimestamp; - /** - * Maximum deposit fee covered by the merchant. - */ - max_fee: string; - /** - * Information about the merchant. - */ merchant: MerchantInfo; - /** - * Public key of the merchant. - */ merchant_pub: string; - /** - * Time indicating when the order should be delivered. - * May be overwritten by individual products. - */ delivery_date?: TalerProtocolTimestamp; - /** - * Delivery location for (all!) products. - */ delivery_location?: Location; - /** - * List of accepted exchanges. - */ exchanges: ExchangeHandle[]; - /** - * Products that are sold in this contract. - */ products?: Product[]; - /** - * Deadline for refunds. - */ refund_deadline: TalerProtocolTimestamp; - /** - * Deadline for the wire transfer. - */ wire_transfer_deadline: TalerProtocolTimestamp; - /** - * Time when the contract was generated by the merchant. - */ timestamp: TalerProtocolTimestamp; - /** - * Order id to uniquely identify the purchase within - * one merchant instance. - */ - order_id: string; - /** - * Base URL of the merchant's backend. - */ merchant_base_url: string; - /** - * Fulfillment URL to view the product or - * delivery status. - */ fulfillment_url?: string; - /** - * URL meant to share the shopping cart. - */ public_reorder_url?: string; - /** - * Plain text fulfillment message in the merchant's default language. - */ fulfillment_message?: string; - /** - * Internationalized fulfillment messages. - */ fulfillment_message_i18n?: InternationalizedString; - /** - * Share of the wire fee that must be settled with one payment. - */ - wire_fee_amortization?: number; - /** - * Maximum wire fee that the merchant agrees to pay for. - */ - max_wire_fee?: string; - minimum_age?: number; - /** - * Extra data, interpreted by the mechant only. - */ + max_fee: string; extra?: any; -} -``` -```typescript -export interface AuditorHandle { - /** - * Official name of the auditor. - */ - name: string; - /** - * Master public signing key of the auditor. - */ - auditor_pub: string; - /** - * Base URL of the auditor. - */ - url: string; + minimum_age?: Integer; } ``` ```typescript @@ -3406,21 +3938,34 @@ export interface AuditorHandle { * merchant's contract terms. */ export interface ExchangeHandle { - /** - * Master public signing key of the exchange. - */ - master_pub: string; - /** - * Base URL of the exchange. - */ url: string; + master_pub: EddsaPublicKeyString; +} +``` +```typescript +export interface Product { + product_id?: string; + description: string; + description_i18n?: InternationalizedString; + quantity?: Integer; + unit?: string; + price?: AmountString; + image?: ImageDataUrl; + taxes?: Tax[]; + delivery_date?: TalerProtocolTimestamp; +} +``` +```typescript +export interface Tax { + name: string; + tax: AmountString; } ``` ```typescript /** * Detailed reason for why the wallet's balance is insufficient. */ -export interface PayMerchantInsufficientBalanceDetails { +export interface PaymentInsufficientBalanceDetails { /** * Amount requested by the merchant. */ @@ -3440,33 +3985,49 @@ export interface PayMerchantInsufficientBalanceDetails { /** * Balance of type "merchant-acceptable" (see balance.ts for definition). */ - balanceMerchantAcceptable: AmountString; + balanceReceiverAcceptable: AmountString; /** * Balance of type "merchant-depositable" (see balance.ts for definition). */ - balanceMerchantDepositable: AmountString; - /** - * If the payment would succeed without fees - * (i.e. balanceMechantWireable >= amountRequested), - * this field contains an estimate of the amount that would additionally - * be required to cover the fees. - * - * It is not possible to give an exact value here, since it depends - * on the coin selection for the amount that would be additionally withdrawn. - */ - feeGapEstimate: AmountString; + balanceReceiverDepositable: AmountString; + balanceExchangeDepositable: AmountString; + /** + * Maximum effective amount that the wallet can spend, + * when all fees are paid by the wallet. + */ + maxEffectiveSpendAmount: AmountString; + perExchange: { + [url: string]: { + balanceAvailable: AmountString; + balanceMaterial: AmountString; + balanceExchangeDepositable: AmountString; + balanceAgeAcceptable: AmountString; + balanceReceiverAcceptable: AmountString; + balanceReceiverDepositable: AmountString; + maxEffectiveSpendAmount: AmountString; + /** + * Exchange doesn't have global fees configured for the relevant year, + * p2p payments aren't possible. + */ + missingGlobalFees: boolean; + }; + }; } ``` ```typescript export interface PreparePayResultAlreadyConfirmed { status: PreparePayResultType.AlreadyConfirmed; + transactionId: TransactionIdStr; contractTerms: MerchantContractTerms; paid: boolean; - amountRaw: string; - amountEffective: string; + amountRaw: AmountString; + amountEffective: AmountString | undefined; contractTermsHash: string; + /** + * @deprecated use transactionId + */ proposalId: string; - talerUri?: string; + talerUri: string; } ``` ```typescript @@ -3475,12 +4036,15 @@ export interface PreparePayResultAlreadyConfirmed { */ export interface PreparePayResultPaymentPossible { status: PreparePayResultType.PaymentPossible; + transactionId: TransactionIdStr; + /** + * @deprecated use transactionId instead + */ proposalId: string; contractTerms: MerchantContractTerms; contractTermsHash: string; - amountRaw: string; - amountEffective: string; - noncePriv: string; + amountRaw: AmountString; + amountEffective: AmountString; talerUri: string; } ``` @@ -3496,21 +4060,18 @@ export interface ForcedCoinSel { } ``` ```typescript -export interface ApplyRefundResponse { - contractTermsHash: string; - transactionId: string; - proposalId: string; - amountEffectivePaid: AmountString; - amountRefundGranted: AmountString; - amountRefundGone: AmountString; - pendingAtExchange: boolean; - info: OrderShortInfo; +export interface AddExchangeRequest { + exchangeBaseUrl: string; + /** + * @deprecated use a separate API call to start a forced exchange update instead + */ + forceUpdate?: boolean; + masterPub?: string; } ``` ```typescript -export interface AddExchangeRequest { +export interface AcceptExchangeTosRequest { exchangeBaseUrl: string; - forceUpdate?: boolean; } ``` ```typescript @@ -3532,3 +4093,13 @@ export interface PeerContractTerms { purse_expiration: TalerProtocolTimestamp; } ``` +```typescript +export interface IntegrationTestArgs { + exchangeBaseUrl: string; + corebankApiBaseUrl: string; + merchantBaseUrl: string; + merchantAuthToken?: string; + amountToWithdraw: AmountString; + amountToSpend: AmountString; +} +``` |