notifications.rst (15636B)
1 .. _wallet-notif-coin-recovery-progress: 2 3 **coin-recovery-progress** 4 5 Emitted while the :ts:op:`testingRecoverCoins` 6 operation scans an exchange for coins that belong to the wallet and recovers 7 them. The ``progressToken`` matches the progress token of the initiating 8 request. 9 10 The payload is a `CoinRecoveryProgressNotification` object. 11 12 .. ts:def:: CoinRecoveryProgressNotification 13 14 interface CoinRecoveryProgressNotification { 15 type: NotificationType.CoinRecoveryProgress; 16 exchangeBaseUrl: string; 17 progressToken: string; 18 phase: CoinRecoveryPhase; 19 numChecked: number; 20 numDiscovered: number; 21 numQueued: number; 22 numRecovered: number; 23 recoveredAmount: AmountString; 24 numIssues: number; 25 } 26 27 .. ts:def:: CoinRecoveryPhase 28 29 type CoinRecoveryPhase = 30 | "starting" 31 | "history" 32 | "derive" 33 | "melt" 34 | "reveal" 35 | "refresh" 36 | "complete" 37 | "incomplete" 38 | "failed" 39 | "cancelled"; 40 41 42 .. _wallet-notif-balance-change: 43 44 **balance-change** 45 46 Indicates a change to the balance overview, including amounts, scope 47 membership, capabilities, donation summaries or expiration-risk flags. 48 A new scope can have a zero available balance. Clients should re-query 49 :ts:op:`getBalances` in response. 50 51 The payload is a `BalanceChangeNotification` object. 52 53 .. ts:def:: BalanceChangeNotification 54 55 interface BalanceChangeNotification { 56 type: NotificationType.BalanceChange; 57 58 // If set to true, the balance change is internal to the wallet 59 // and not visible to the user. (For example when the material 60 // balance changes via a refresh, but the available balance 61 // stays the same.) 62 isInternal?: boolean; 63 64 // Transaction ID of the transaction that caused the balance 65 // update. Only used as a hint for debugging, should not be 66 // relied upon by clients. 67 hintTransactionId?: string; 68 } 69 70 71 .. _wallet-notif-bank-account-change: 72 73 **bank-account-change** 74 75 Emitted when a bank account known to the wallet was added, changed or 76 deleted. Clients should re-query 77 :ts:op:`listBankAccounts`. 78 79 The payload is a `BankAccountChangeNotification` object. 80 81 .. ts:def:: BankAccountChangeNotification 82 83 interface BankAccountChangeNotification { 84 type: NotificationType.BankAccountChange; 85 86 // ID of the affected bank account. 87 bankAccountId: string; 88 } 89 90 91 .. _wallet-notif-backup-error: 92 93 **backup-error** 94 95 Signals the failure of a backup operation. The current wallet-core 96 implementation does not emit this notification. 97 98 The payload is a `BackupOperationErrorNotification` object. 99 100 .. ts:def:: BackupOperationErrorNotification 101 102 interface BackupOperationErrorNotification { 103 type: NotificationType.BackupOperationError; 104 error: TalerErrorDetail; 105 } 106 107 108 .. _wallet-notif-contact-added: 109 110 **contact-added** 111 112 Emitted when a contact was added to the wallet's address book. Clients 113 should re-query :ts:op:`getContacts`. 114 115 The payload is a `ContactAddedNotification` object. 116 117 .. ts:def:: ContactAddedNotification 118 119 interface ContactAddedNotification { 120 type: NotificationType.ContactAdded; 121 122 // The contact that was added. 123 contact: ContactEntry; 124 } 125 126 127 .. _wallet-notif-contact-deleted: 128 129 **contact-deleted** 130 131 Emitted when a contact was deleted from the wallet's address book. Clients 132 should re-query :ts:op:`getContacts`. 133 134 The payload is a `ContactDeletedNotification` object. 135 136 .. ts:def:: ContactDeletedNotification 137 138 interface ContactDeletedNotification { 139 type: NotificationType.ContactDeleted; 140 141 // The contact that was deleted. 142 contact: ContactEntry; 143 } 144 145 146 .. _wallet-notif-mailbox-message-added: 147 148 **mailbox-message-added** 149 150 Emitted when a message was added to the wallet's mailbox, for example a 151 payment request received from another wallet user. 152 153 The payload is a `MailboxMessageAddedNotification` object. 154 155 .. ts:def:: MailboxMessageAddedNotification 156 157 interface MailboxMessageAddedNotification { 158 type: NotificationType.MailboxMessageAdded; 159 160 // The message that was added. 161 message: MailboxMessageRecord; 162 } 163 164 165 .. _wallet-notif-mailbox-message-deleted: 166 167 **mailbox-message-deleted** 168 169 Emitted when a message was deleted from the wallet's mailbox. 170 171 The payload is a `MailboxMessageDeletedNotification` object. 172 173 .. ts:def:: MailboxMessageDeletedNotification 174 175 interface MailboxMessageDeletedNotification { 176 type: NotificationType.MailboxMessageDeleted; 177 178 // The message that was deleted. 179 message: MailboxMessageRecord; 180 } 181 182 183 .. _wallet-notif-transaction-state-transition: 184 185 **transaction-state-transition** 186 187 Emitted when a transaction moves from one state to another. Clients should 188 re-query the affected transaction; the ``causeHint`` is only a debugging 189 aid and must not be relied upon. 190 191 The payload is a `TransactionStateTransitionNotification` object. 192 193 .. ts:def:: TransactionStateTransitionNotification 194 195 interface TransactionStateTransitionNotification { 196 type: NotificationType.TransactionStateTransition; 197 198 // Identifier of the affected transaction. 199 transactionId: string; 200 201 // A hint as to why the transition happened. 202 // Should not be relied upon by clients. 203 causeHint: string | undefined; 204 205 // State before the transition. 206 oldTxState: TransactionState; 207 208 // State after the transition. 209 newTxState: TransactionState; 210 211 // Internal ID of the new state. Must not be used by the UI, 212 // only used for testing. 213 newStId: number; 214 215 // Short summary of the error for an error transition. 216 errorInfo?: ErrorInfoSummary; 217 } 218 219 .. ts:def:: ErrorInfoSummary 220 221 interface ErrorInfoSummary { 222 code: number; 223 hint?: string; 224 message?: string; 225 } 226 227 228 .. _wallet-notif-exchange-state-transition: 229 230 **exchange-state-transition** 231 232 Emitted when the public state or substantive details of an exchange change. 233 Equal states may accompany changed fees, keys, terms or KYC information. 234 Updating the last-check timestamp alone does not emit this event. If 235 ``oldExchangeState`` is missing, the entry was newly created; if 236 ``newExchangeState`` is missing, the entry was deleted. 237 238 The payload is an `ExchangeStateTransitionNotification` object. 239 240 .. ts:def:: ExchangeStateTransitionNotification 241 242 interface ExchangeStateTransitionNotification { 243 type: NotificationType.ExchangeStateTransition; 244 245 // Identification of the exchange entry that this 246 // notification is about. 247 exchangeBaseUrl: string; 248 249 // A hint as to why the transition happened. 250 // Should not be relied upon by clients. 251 causeHint: string | undefined; 252 253 // If missing, the notification means that 254 // the exchange entry is newly created. 255 oldExchangeState?: ExchangeEntryState; 256 257 // New state of the exchange. 258 // If missing, the exchange entry got deleted. 259 newExchangeState?: ExchangeEntryState; 260 261 // Summary of the error that occurred when trying to update 262 // the exchange entry, if applicable. 263 errorInfo?: ErrorInfoSummary; 264 } 265 266 .. ts:def:: ExchangeEntryState 267 268 interface ExchangeEntryState { 269 // Status of the exchange's terms of service. 270 tosStatus: ExchangeTosStatus; 271 272 // Lifecycle status of the exchange entry. 273 exchangeEntryStatus: ExchangeEntryStatus; 274 275 // Status of the last update of the exchange's key material. 276 exchangeUpdateStatus: ExchangeUpdateStatus; 277 } 278 279 280 .. _wallet-notif-idle: 281 282 **idle** 283 284 Emitted when wallet-core becomes idle, that is when no background task 285 that keeps the wallet active is running anymore. Mainly useful for test 286 harnesses that wait for the wallet to quiesce. 287 288 The payload is an `IdleNotification` object. 289 290 .. ts:def:: IdleNotification 291 292 interface IdleNotification { 293 type: NotificationType.Idle; 294 } 295 296 297 .. _wallet-notif-task-observability-event: 298 299 **task-observability-event** 300 301 Reports a single observability event of a background task. These 302 notifications are only emitted when the testing option 303 ``emitObservabilityEvents`` is enabled in the wallet run configuration. 304 305 The payload is a `TaskProgressNotification` object. 306 307 .. ts:def:: TaskProgressNotification 308 309 interface TaskProgressNotification { 310 type: NotificationType.TaskObservabilityEvent; 311 taskId: string; 312 event: ObservabilityEvent; 313 } 314 315 .. ts:def:: ObservabilityEvent 316 317 type ObservabilityEvent = 318 | { 319 id: string; 320 when: AbsoluteTime; 321 type: ObservabilityEventType.HttpFetchStart; 322 url: string; 323 longPolling: boolean; 324 } 325 | { 326 id: string; 327 when: AbsoluteTime; 328 type: ObservabilityEventType.HttpFetchFinishSuccess; 329 url: string; 330 status: number; 331 durationMs: number; 332 longPolling: boolean; 333 } 334 | { 335 id: string; 336 when: AbsoluteTime; 337 type: ObservabilityEventType.HttpFetchFinishError; 338 url: string; 339 error: TalerErrorDetail; 340 durationMs: number; 341 longPolling: boolean; 342 } 343 | { 344 type: ObservabilityEventType.DbQueryStart; 345 name: string; 346 location: string; 347 } 348 | { 349 type: ObservabilityEventType.DbQueryFinishSuccess; 350 name: string; 351 location: string; 352 durationMs: number; 353 } 354 | { 355 type: ObservabilityEventType.DbQueryFinishError; 356 name: string; 357 location: string; 358 error: TalerErrorDetail; 359 durationMs: number; 360 } 361 | { 362 type: ObservabilityEventType.RequestStart; 363 name: string; 364 } 365 | { 366 type: ObservabilityEventType.RequestFinishSuccess; 367 operation: string; 368 requestId: string; 369 durationMs: number; 370 } 371 | { 372 type: ObservabilityEventType.RequestFinishError; 373 operation: string; 374 requestId: string; 375 durationMs: number; 376 } 377 | { 378 type: ObservabilityEventType.TaskStart; 379 taskId: string; 380 } 381 | { 382 type: ObservabilityEventType.TaskStop; 383 taskId: string; 384 } 385 | { 386 type: ObservabilityEventType.TaskReset; 387 taskId: string; 388 } 389 | { 390 type: ObservabilityEventType.DeclareTaskDependency; 391 taskId: string; 392 } 393 | { 394 type: ObservabilityEventType.CryptoStart; 395 operation: string; 396 } 397 | { 398 type: ObservabilityEventType.CryptoFinishSuccess; 399 operation: string; 400 durationMs: number; 401 } 402 | { 403 type: ObservabilityEventType.CryptoFinishError; 404 operation: string; 405 durationMs: number; 406 } 407 | { 408 type: ObservabilityEventType.ShepherdTaskResult; 409 taskId: string; 410 resultType: string; 411 durationMs: number; 412 } 413 | { 414 type: ObservabilityEventType.Message; 415 contents: string; 416 } 417 | { 418 type: ObservabilityEventType.DeclareConcernsTransaction; 419 transactionId: TransactionIdStr; 420 }; 421 422 .. ts:def:: ObservabilityEventType 423 424 enum ObservabilityEventType { 425 HttpFetchStart = "http-fetch-start", 426 HttpFetchFinishError = "http-fetch-finish-error", 427 HttpFetchFinishSuccess = "http-fetch-finish-success", 428 DbQueryStart = "db-query-start", 429 DbQueryFinishSuccess = "db-query-finish-success", 430 DbQueryFinishError = "db-query-finish-error", 431 RequestStart = "request-start", 432 RequestFinishSuccess = "request-finish-success", 433 RequestFinishError = "request-finish-error", 434 TaskStart = "task-start", 435 TaskStop = "task-stop", 436 TaskReset = "task-reset", 437 ShepherdTaskResult = "shepherd-task-result", 438 DeclareTaskDependency = "declare-task-dependency", 439 CryptoStart = "crypto-start", 440 CryptoFinishSuccess = "crypto-finish-success", 441 CryptoFinishError = "crypto-finish-error", 442 Message = "message", 443 444 // Declares that an observability event is relevant to a particular 445 // transaction. If emitted from a request/task, all past/future 446 // events for that request/task should be shown for the 447 // transaction as well. 448 DeclareConcernsTransaction = "declare-concerns-transaction", 449 } 450 451 452 .. _wallet-notif-request-observability-event: 453 454 **request-observability-event** 455 456 Reports a single observability event of an API request; ``requestId`` 457 matches the ``id`` of the corresponding request envelope. These 458 notifications are only emitted when the testing option 459 ``emitObservabilityEvents`` is enabled in the wallet run configuration. 460 461 The payload is a `RequestObservabilityEventNotification` object. 462 463 .. ts:def:: RequestObservabilityEventNotification 464 465 interface RequestObservabilityEventNotification { 466 type: NotificationType.RequestObservabilityEvent; 467 requestId: string; 468 operation: string; 469 event: ObservabilityEvent; 470 } 471 472 473 .. _wallet-notif-request-progress-error: 474 475 **request-progress-error** 476 477 Emitted when an attempt of a long-running request with a ``progressToken`` 478 failed and will be retried automatically after ``nextRetryDelay``. The 479 client can cancel the request with 480 :ts:op:`cancelProgressToken` or trigger an 481 immediate retry with 482 :ts:op:`retryProgressTokenNow`. 483 484 The payload is a `RequestProgressNotification` object. 485 486 .. ts:def:: RequestProgressNotification 487 488 interface RequestProgressNotification { 489 type: NotificationType.RequestProgressError; 490 progressToken: string; 491 operation: string; 492 error: TalerErrorDetail; 493 nextRetryDelay: TalerProtocolDuration; 494 retryCounter: number; 495 } 496 497 498 .. _wallet-notif-request-progress-phase: 499 500 **request-progress-phase** 501 502 Emitted when a long-running request with a ``progressToken`` takes longer 503 than expected: ``delayed`` after about five seconds, ``stalled`` after 504 about ten seconds (at which point the user may want to retry), and 505 ``done`` when the request finished and no further progress notifications 506 will be sent. 507 508 The payload is a `RequestProgressPhaseNotification` object. 509 510 .. ts:def:: RequestProgressPhaseNotification 511 512 interface RequestProgressPhaseNotification { 513 type: NotificationType.RequestProgressPhase; 514 progressToken: string; 515 operation: string; 516 517 // delayed: request is taking longer than expected (usually 518 // after 5s) 519 // stalled: request is taking *very* long, user can retry 520 // (usually after 10s) 521 // done: no further progress notifications will be sent 522 phase: "delayed" | "stalled" | "done"; 523 } 524 525 526 .. _wallet-notif-database-maintenance-progress: 527 528 **database-maintenance-progress** 529 530 Emitted while startup fixups or a database migration hold the database 531 gate, reporting progress of the maintenance operation. Intermediate 532 updates may be coalesced by wallet-core, but the first and the terminal 533 (``complete`` or ``failed``) events are always delivered. 534 535 The payload is a `DatabaseMaintenanceProgressNotification` object. 536 537 .. ts:def:: DatabaseMaintenanceProgressNotification 538 539 interface DatabaseMaintenanceProgressNotification { 540 type: NotificationType.DatabaseMaintenanceProgress; 541 operation: 542 | "indexeddb-fixup" 543 | "indexeddb-to-native-migration" 544 | "cross-backend-import"; 545 546 // Token of the API request that initiated this operation, 547 // when available. 548 progressToken?: string; 549 550 phase: "fixup" | "copy" | "verify" | "complete" | "failed"; 551 552 // Current fixup or backend-neutral store, when one is active. 553 step?: string; 554 555 completedSteps: number; 556 totalSteps: number; 557 558 // Records completed in the current phase across the 559 // whole migration. 560 processedRecords?: number; 561 562 // Total records in the whole migration, known before 563 // copying starts. 564 totalRecords?: number; 565 566 // Rough overall migration completion, from 0 through 100. 567 completionPercent?: number; 568 569 // Why the maintenance operation failed. Present when 570 // phase is "failed". 571 error?: TalerErrorDetail; 572 }