taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

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   }