taler-docs

notifications.rst (15446B)

---

 .. _wallet-notif-coin-recovery-progress:
 
 **coin-recovery-progress**
 
 Emitted while the :ts:op:`testingRecoverCoins`
 operation scans an exchange for coins that belong to the wallet and recovers
 them.  The ``progressToken`` matches the progress token of the initiating
 request.
 
 The payload is a `CoinRecoveryProgressNotification` object.
 
 .. ts:def:: CoinRecoveryProgressNotification
 
   interface CoinRecoveryProgressNotification {
     type: NotificationType.CoinRecoveryProgress;
     exchangeBaseUrl: string;
     progressToken: string;
     phase: CoinRecoveryPhase;
     numChecked: number;
     numDiscovered: number;
     numQueued: number;
     numRecovered: number;
     recoveredAmount: AmountString;
     numIssues: number;
   }
 
 .. ts:def:: CoinRecoveryPhase
 
   type CoinRecoveryPhase =
     | "starting"
     | "history"
     | "derive"
     | "melt"
     | "reveal"
     | "refresh"
     | "complete"
     | "incomplete"
     | "failed"
     | "cancelled";
 
 
 .. _wallet-notif-balance-change:
 
 **balance-change**
 
 Invalidates balance data, including flags and refresh information.  The
 monetary amounts need not have changed, for example when a refresh cost
 becomes ready.  Clients should re-query
 :ts:op:`getBalances` in response.
 
 The payload is a `BalanceChangeNotification` object.
 
 .. ts:def:: BalanceChangeNotification
 
   interface BalanceChangeNotification {
     type: NotificationType.BalanceChange;
 
     // If set to true, the balance change is internal to the wallet
     // and not visible to the user.  (For example when the material
     // balance changes via a refresh, but the available balance
     // stays the same.)
     isInternal?: boolean;
 
     // Transaction ID of the transaction that caused the balance
     // update.  Only used as a hint for debugging, should not be
     // relied upon by clients.
     hintTransactionId: string;
   }
 
 
 .. _wallet-notif-bank-account-change:
 
 **bank-account-change**
 
 Emitted when a bank account known to the wallet was added, changed or
 deleted.  Clients should re-query
 :ts:op:`listBankAccounts`.
 
 The payload is a `BankAccountChangeNotification` object.
 
 .. ts:def:: BankAccountChangeNotification
 
   interface BankAccountChangeNotification {
     type: NotificationType.BankAccountChange;
 
     // ID of the affected bank account.
     bankAccountId: string;
   }
 
 
 .. _wallet-notif-backup-error:
 
 **backup-error**
 
 Signals the failure of a backup operation.  The current wallet-core
 implementation does not emit this notification.
 
 The payload is a `BackupOperationErrorNotification` object.
 
 .. ts:def:: BackupOperationErrorNotification
 
   interface BackupOperationErrorNotification {
     type: NotificationType.BackupOperationError;
     error: TalerErrorDetail;
   }
 
 
 .. _wallet-notif-contact-added:
 
 **contact-added**
 
 Emitted when a contact was added to the wallet's address book.  Clients
 should re-query :ts:op:`getContacts`.
 
 The payload is a `ContactAddedNotification` object.
 
 .. ts:def:: ContactAddedNotification
 
   interface ContactAddedNotification {
     type: NotificationType.ContactAdded;
 
     // The contact that was added.
     contact: ContactEntry;
   }
 
 
 .. _wallet-notif-contact-deleted:
 
 **contact-deleted**
 
 Emitted when a contact was deleted from the wallet's address book.  Clients
 should re-query :ts:op:`getContacts`.
 
 The payload is a `ContactDeletedNotification` object.
 
 .. ts:def:: ContactDeletedNotification
 
   interface ContactDeletedNotification {
     type: NotificationType.ContactDeleted;
 
     // The contact that was deleted.
     contact: ContactEntry;
   }
 
 
 .. _wallet-notif-mailbox-message-added:
 
 **mailbox-message-added**
 
 Emitted when a message was added to the wallet's mailbox, for example a
 payment request received from another wallet user.
 
 The payload is a `MailboxMessageAddedNotification` object.
 
 .. ts:def:: MailboxMessageAddedNotification
 
   interface MailboxMessageAddedNotification {
     type: NotificationType.MailboxMessageAdded;
 
     // The message that was added.
     message: MailboxMessageRecord;
   }
 
 
 .. _wallet-notif-mailbox-message-deleted:
 
 **mailbox-message-deleted**
 
 Emitted when a message was deleted from the wallet's mailbox.
 
 The payload is a `MailboxMessageDeletedNotification` object.
 
 .. ts:def:: MailboxMessageDeletedNotification
 
   interface MailboxMessageDeletedNotification {
     type: NotificationType.MailboxMessageDeleted;
 
     // The message that was deleted.
     message: MailboxMessageRecord;
   }
 
 
 .. _wallet-notif-transaction-state-transition:
 
 **transaction-state-transition**
 
 Emitted when a transaction moves from one state to another.  Clients should
 re-query the affected transaction; the ``causeHint`` is only a debugging
 aid and must not be relied upon.
 
 The payload is a `TransactionStateTransitionNotification` object.
 
 .. ts:def:: TransactionStateTransitionNotification
 
   interface TransactionStateTransitionNotification {
     type: NotificationType.TransactionStateTransition;
 
     // Identifier of the affected transaction.
     transactionId: string;
 
     // A hint as to why the transition happened.
     // Should not be relied upon by clients.
     causeHint: string | undefined;
 
     // State before the transition.
     oldTxState: TransactionState;
 
     // State after the transition.
     newTxState: TransactionState;
 
     // Internal ID of the new state.  Must not be used by the UI,
     // only used for testing.
     newStId: number;
 
     // Short summary of the error for an error transition.
     errorInfo?: ErrorInfoSummary;
   }
 
 .. ts:def:: ErrorInfoSummary
 
   interface ErrorInfoSummary {
     code: number;
     hint?: string;
     message?: string;
   }
 
 
 .. _wallet-notif-exchange-state-transition:
 
 **exchange-state-transition**
 
 Emitted when the state of an exchange entry changes.  If
 ``oldExchangeState`` is missing, the entry was newly created; if
 ``newExchangeState`` is missing, the entry was deleted.
 
 The payload is an `ExchangeStateTransitionNotification` object.
 
 .. ts:def:: ExchangeStateTransitionNotification
 
   interface ExchangeStateTransitionNotification {
     type: NotificationType.ExchangeStateTransition;
 
     // Identification of the exchange entry that this
     // notification is about.
     exchangeBaseUrl: string;
 
     // A hint as to why the transition happened.
     // Should not be relied upon by clients.
     causeHint: string | undefined;
 
     // If missing, the notification means that
     // the exchange entry is newly created.
     oldExchangeState?: ExchangeEntryState;
 
     // New state of the exchange.
     // If missing, the exchange entry got deleted.
     newExchangeState?: ExchangeEntryState;
 
     // Summary of the error that occurred when trying to update
     // the exchange entry, if applicable.
     errorInfo?: ErrorInfoSummary;
   }
 
 .. ts:def:: ExchangeEntryState
 
   interface ExchangeEntryState {
     // Status of the exchange's terms of service.
     tosStatus: ExchangeTosStatus;
 
     // Lifecycle status of the exchange entry.
     exchangeEntryStatus: ExchangeEntryStatus;
 
     // Status of the last update of the exchange's key material.
     exchangeUpdateStatus: ExchangeUpdateStatus;
   }
 
 
 .. _wallet-notif-idle:
 
 **idle**
 
 Emitted when wallet-core becomes idle, that is when no background task
 that keeps the wallet active is running anymore.  Mainly useful for test
 harnesses that wait for the wallet to quiesce.
 
 The payload is an `IdleNotification` object.
 
 .. ts:def:: IdleNotification
 
   interface IdleNotification {
     type: NotificationType.Idle;
   }
 
 
 .. _wallet-notif-task-observability-event:
 
 **task-observability-event**
 
 Reports a single observability event of a background task.  These
 notifications are only emitted when the testing option
 ``emitObservabilityEvents`` is enabled in the wallet run configuration.
 
 The payload is a `TaskProgressNotification` object.
 
 .. ts:def:: TaskProgressNotification
 
   interface TaskProgressNotification {
     type: NotificationType.TaskObservabilityEvent;
     taskId: string;
     event: ObservabilityEvent;
   }
 
 .. ts:def:: ObservabilityEvent
 
   type ObservabilityEvent =
     | {
         id: string;
         when: AbsoluteTime;
         type: ObservabilityEventType.HttpFetchStart;
         url: string;
         longPolling: boolean;
       }
     | {
         id: string;
         when: AbsoluteTime;
         type: ObservabilityEventType.HttpFetchFinishSuccess;
         url: string;
         status: number;
         durationMs: number;
         longPolling: boolean;
       }
     | {
         id: string;
         when: AbsoluteTime;
         type: ObservabilityEventType.HttpFetchFinishError;
         url: string;
         error: TalerErrorDetail;
         durationMs: number;
         longPolling: boolean;
       }
     | {
         type: ObservabilityEventType.DbQueryStart;
         name: string;
         location: string;
       }
     | {
         type: ObservabilityEventType.DbQueryFinishSuccess;
         name: string;
         location: string;
         durationMs: number;
       }
     | {
         type: ObservabilityEventType.DbQueryFinishError;
         name: string;
         location: string;
         error: TalerErrorDetail;
         durationMs: number;
       }
     | {
         type: ObservabilityEventType.RequestStart;
         name: string;
       }
     | {
         type: ObservabilityEventType.RequestFinishSuccess;
         operation: string;
         requestId: string;
         durationMs: number;
       }
     | {
         type: ObservabilityEventType.RequestFinishError;
         operation: string;
         requestId: string;
         durationMs: number;
       }
     | {
         type: ObservabilityEventType.TaskStart;
         taskId: string;
       }
     | {
         type: ObservabilityEventType.TaskStop;
         taskId: string;
       }
     | {
         type: ObservabilityEventType.TaskReset;
         taskId: string;
       }
     | {
         type: ObservabilityEventType.DeclareTaskDependency;
         taskId: string;
       }
     | {
         type: ObservabilityEventType.CryptoStart;
         operation: string;
       }
     | {
         type: ObservabilityEventType.CryptoFinishSuccess;
         operation: string;
         durationMs: number;
       }
     | {
         type: ObservabilityEventType.CryptoFinishError;
         operation: string;
         durationMs: number;
       }
     | {
         type: ObservabilityEventType.ShepherdTaskResult;
         taskId: string;
         resultType: string;
         durationMs: number;
       }
     | {
         type: ObservabilityEventType.Message;
         contents: string;
       }
     | {
         type: ObservabilityEventType.DeclareConcernsTransaction;
         transactionId: TransactionIdStr;
       };
 
 .. ts:def:: ObservabilityEventType
 
   enum ObservabilityEventType {
     HttpFetchStart = "http-fetch-start",
     HttpFetchFinishError = "http-fetch-finish-error",
     HttpFetchFinishSuccess = "http-fetch-finish-success",
     DbQueryStart = "db-query-start",
     DbQueryFinishSuccess = "db-query-finish-success",
     DbQueryFinishError = "db-query-finish-error",
     RequestStart = "request-start",
     RequestFinishSuccess = "request-finish-success",
     RequestFinishError = "request-finish-error",
     TaskStart = "task-start",
     TaskStop = "task-stop",
     TaskReset = "task-reset",
     ShepherdTaskResult = "shepherd-task-result",
     DeclareTaskDependency = "declare-task-dependency",
     CryptoStart = "crypto-start",
     CryptoFinishSuccess = "crypto-finish-success",
     CryptoFinishError = "crypto-finish-error",
     Message = "message",
 
     // Declares that an observability event is relevant to a particular
     // transaction.  If emitted from a request/task, all past/future
     // events for that request/task should be shown for the
     // transaction as well.
     DeclareConcernsTransaction = "declare-concerns-transaction",
   }
 
 
 .. _wallet-notif-request-observability-event:
 
 **request-observability-event**
 
 Reports a single observability event of an API request; ``requestId``
 matches the ``id`` of the corresponding request envelope.  These
 notifications are only emitted when the testing option
 ``emitObservabilityEvents`` is enabled in the wallet run configuration.
 
 The payload is a `RequestObservabilityEventNotification` object.
 
 .. ts:def:: RequestObservabilityEventNotification
 
   interface RequestObservabilityEventNotification {
     type: NotificationType.RequestObservabilityEvent;
     requestId: string;
     operation: string;
     event: ObservabilityEvent;
   }
 
 
 .. _wallet-notif-request-progress-error:
 
 **request-progress-error**
 
 Emitted when an attempt of a long-running request with a ``progressToken``
 failed and will be retried automatically after ``nextRetryDelay``.  The
 client can cancel the request with
 :ts:op:`cancelProgressToken` or trigger an
 immediate retry with
 :ts:op:`retryProgressTokenNow`.
 
 The payload is a `RequestProgressNotification` object.
 
 .. ts:def:: RequestProgressNotification
 
   interface RequestProgressNotification {
     type: NotificationType.RequestProgressError;
     progressToken: string;
     operation: string;
     error: TalerErrorDetail;
     nextRetryDelay: TalerProtocolDuration;
     retryCounter: number;
   }
 
 
 .. _wallet-notif-request-progress-phase:
 
 **request-progress-phase**
 
 Emitted when a long-running request with a ``progressToken`` takes longer
 than expected: ``delayed`` after about five seconds, ``stalled`` after
 about ten seconds (at which point the user may want to retry), and
 ``done`` when the request finished and no further progress notifications
 will be sent.
 
 The payload is a `RequestProgressPhaseNotification` object.
 
 .. ts:def:: RequestProgressPhaseNotification
 
   interface RequestProgressPhaseNotification {
     type: NotificationType.RequestProgressPhase;
     progressToken: string;
     operation: string;
 
     // delayed: request is taking longer than expected (usually
     //   after 5s)
     // stalled: request is taking *very* long, user can retry
     //   (usually after 10s)
     // done: no further progress notifications will be sent
     phase: "delayed" | "stalled" | "done";
   }
 
 
 .. _wallet-notif-database-maintenance-progress:
 
 **database-maintenance-progress**
 
 Emitted while startup fixups or a database migration hold the database
 gate, reporting progress of the maintenance operation.  Intermediate
 updates may be coalesced by wallet-core, but the first and the terminal
 (``complete`` or ``failed``) events are always delivered.
 
 The payload is a `DatabaseMaintenanceProgressNotification` object.
 
 .. ts:def:: DatabaseMaintenanceProgressNotification
 
   interface DatabaseMaintenanceProgressNotification {
     type: NotificationType.DatabaseMaintenanceProgress;
     operation:
       | "indexeddb-fixup"
       | "indexeddb-to-native-migration"
       | "cross-backend-import";
 
     // Token of the API request that initiated this operation,
     // when available.
     progressToken?: string;
 
     phase: "fixup" | "copy" | "verify" | "complete" | "failed";
 
     // Current fixup or backend-neutral store, when one is active.
     step?: string;
 
     completedSteps: number;
     totalSteps: number;
 
     // Records completed in the current phase across the
     // whole migration.
     processedRecords?: number;
 
     // Total records in the whole migration, known before
     // copying starts.
     totalRecords?: number;
 
     // Rough overall migration completion, from 0 through 100.
     completionPercent?: number;
 
     // Why the maintenance operation failed.  Present when
     // phase is "failed".
     error?: TalerErrorDetail;
   }