@metamask-previews/network-connection-banner-controller 0.1.0-preview-fe651cdb3 → 0.1.0-preview-cadd612bb

package/CHANGELOG.md

@@ -9,6 +9,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- Initial release ([#9041](https://github.com/MetaMask/core/pull/9041))
+- Add `NetworkConnectionBannerController`, which evaluates enabled network RPC
+  health after initialization and manages degraded and unavailable banner state,
+  dismissal, and switching custom RPC endpoints to an available Infura endpoint
+  ([#9041](https://github.com/MetaMask/core/pull/9041))
 
 [Unreleased]: https://github.com/MetaMask/core/

package/README.md

@@ -5,6 +5,27 @@ connection banner based on RPC endpoint health. It encapsulates the shared
 rule, the 5s/30s timer state machine, and the eTLD+1 grouping previously
 duplicated across MetaMask clients.
 
+## Lifecycle
+
+The controller stays dormant after construction so the 5s / 30s escalation
+timers do not run before a user is actually looking at the wallet (e.g. while
+the app is still on the lock screen). The UI that renders the banner is
+responsible for driving the lifecycle:
+
+```typescript
+// When the wallet UI that shows the banner becomes active
+// (e.g. the home surface mounts after unlock):
+networkConnectionBannerController.start();
+
+// When it goes away:
+networkConnectionBannerController.stop();
+```
+
+Both methods are idempotent. `start` runs the initial evaluation immediately
+and enables reactions to upstream state changes. `stop` cancels any pending
+timers and resets the banner state to `available`. Upstream state changes are
+ignored while stopped.
+
 ## Installation
 
 `yarn add @metamask/network-connection-banner-controller`

package/dist/NetworkConnectionBannerController-method-action-types.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"NetworkConnectionBannerController-method-action-types.cjs","sourceRoot":"","sources":["../src/NetworkConnectionBannerController-method-action-types.ts"],"names":[],"mappings":";AAAA;;;GAGG","sourcesContent":["/**\n * This file is auto generated.\n * Do not edit manually.\n */\n\nimport type { NetworkConnectionBannerController } from './NetworkConnectionBannerController';\n\n/**\n * Clears the banner state regardless of the current rule outcome. The next\n * subscription-driven evaluation will re-show the banner if the conditions\n * still hold.\n */\nexport type NetworkConnectionBannerControllerDismissBannerAction = {\n  type: `NetworkConnectionBannerController:dismissBanner`;\n  handler: NetworkConnectionBannerController['dismissBanner'];\n};\n\n/**\n * Switches the chain's default RPC endpoint to its first Infura endpoint,\n * causing the banner to clear once the network becomes available again.\n *\n * @param args - The arguments to this action.\n * @param args.chainId - The chain whose default RPC should be switched.\n * @throws If the chain configuration cannot be found, or if it has no\n * Infura endpoint to switch to, or if the default is already Infura.\n */\nexport type NetworkConnectionBannerControllerSwitchToDefaultInfuraRpcAction = {\n  type: `NetworkConnectionBannerController:switchToDefaultInfuraRpc`;\n  handler: NetworkConnectionBannerController['switchToDefaultInfuraRpc'];\n};\n\n/**\n * Union of all NetworkConnectionBannerController action types.\n */\nexport type NetworkConnectionBannerControllerMethodActions =\n  | NetworkConnectionBannerControllerDismissBannerAction\n  | NetworkConnectionBannerControllerSwitchToDefaultInfuraRpcAction;\n"]}
+{"version":3,"file":"NetworkConnectionBannerController-method-action-types.cjs","sourceRoot":"","sources":["../src/NetworkConnectionBannerController-method-action-types.ts"],"names":[],"mappings":";AAAA;;;GAGG","sourcesContent":["/**\n * This file is auto generated.\n * Do not edit manually.\n */\n\nimport type { NetworkConnectionBannerController } from './NetworkConnectionBannerController';\n\n/**\n * Look for a failed network, if any, and populate the initial state of the\n * banner. Reacts to upstream state changes from this point on.\n *\n * Call this when the wallet UI that consumes the banner becomes active\n * (typically when the wallet is unlocked and the home surface mounts) so\n * timers do not run while the user is not looking at the wallet. Should\n * be called after `NetworkController`, `NetworkEnablementController`, and\n * `ConnectivityController` have been initialized. Idempotent.\n */\nexport type NetworkConnectionBannerControllerStartAction = {\n  type: `NetworkConnectionBannerController:start`;\n  handler: NetworkConnectionBannerController['start'];\n};\n\n/**\n * Stops evaluating network connection state. Clears any pending banner\n * timers and resets state to `available`. Call this when the UI\n * consuming the banner is no longer active. Idempotent.\n */\nexport type NetworkConnectionBannerControllerStopAction = {\n  type: `NetworkConnectionBannerController:stop`;\n  handler: NetworkConnectionBannerController['stop'];\n};\n\n/**\n * Clears the banner state such that the banner will be hidden.\n */\nexport type NetworkConnectionBannerControllerDismissBannerAction = {\n  type: `NetworkConnectionBannerController:dismissBanner`;\n  handler: NetworkConnectionBannerController['dismissBanner'];\n};\n\n/**\n * Switches the chain's default RPC endpoint to its Infura endpoint,\n * causing the banner to clear once the network becomes available again.\n *\n * @param chainId - The chain whose default RPC endpoint should be switched.\n * @throws If the chain configuration cannot be found, or if it has no\n * Infura endpoint to switch to, or if the default is already Infura.\n */\nexport type NetworkConnectionBannerControllerSwitchToDefaultInfuraRpcEndpointAction =\n  {\n    type: `NetworkConnectionBannerController:switchToDefaultInfuraRpcEndpoint`;\n    handler: NetworkConnectionBannerController['switchToDefaultInfuraRpcEndpoint'];\n  };\n\n/**\n * Union of all NetworkConnectionBannerController action types.\n */\nexport type NetworkConnectionBannerControllerMethodActions =\n  | NetworkConnectionBannerControllerStartAction\n  | NetworkConnectionBannerControllerStopAction\n  | NetworkConnectionBannerControllerDismissBannerAction\n  | NetworkConnectionBannerControllerSwitchToDefaultInfuraRpcEndpointAction;\n"]}

package/dist/NetworkConnectionBannerController-method-action-types.d.cts

@@ -4,29 +4,49 @@
  */
 import type { NetworkConnectionBannerController } from "./NetworkConnectionBannerController.cjs";
 /**
- * Clears the banner state regardless of the current rule outcome. The next
- * subscription-driven evaluation will re-show the banner if the conditions
- * still hold.
+ * Look for a failed network, if any, and populate the initial state of the
+ * banner. Reacts to upstream state changes from this point on.
+ *
+ * Call this when the wallet UI that consumes the banner becomes active
+ * (typically when the wallet is unlocked and the home surface mounts) so
+ * timers do not run while the user is not looking at the wallet. Should
+ * be called after `NetworkController`, `NetworkEnablementController`, and
+ * `ConnectivityController` have been initialized. Idempotent.
+ */
+export type NetworkConnectionBannerControllerStartAction = {
+    type: `NetworkConnectionBannerController:start`;
+    handler: NetworkConnectionBannerController['start'];
+};
+/**
+ * Stops evaluating network connection state. Clears any pending banner
+ * timers and resets state to `available`. Call this when the UI
+ * consuming the banner is no longer active. Idempotent.
+ */
+export type NetworkConnectionBannerControllerStopAction = {
+    type: `NetworkConnectionBannerController:stop`;
+    handler: NetworkConnectionBannerController['stop'];
+};
+/**
+ * Clears the banner state such that the banner will be hidden.
  */
 export type NetworkConnectionBannerControllerDismissBannerAction = {
     type: `NetworkConnectionBannerController:dismissBanner`;
     handler: NetworkConnectionBannerController['dismissBanner'];
 };
 /**
- * Switches the chain's default RPC endpoint to its first Infura endpoint,
+ * Switches the chain's default RPC endpoint to its Infura endpoint,
  * causing the banner to clear once the network becomes available again.
  *
- * @param args - The arguments to this action.
- * @param args.chainId - The chain whose default RPC should be switched.
+ * @param chainId - The chain whose default RPC endpoint should be switched.
  * @throws If the chain configuration cannot be found, or if it has no
  * Infura endpoint to switch to, or if the default is already Infura.
  */
-export type NetworkConnectionBannerControllerSwitchToDefaultInfuraRpcAction = {
-    type: `NetworkConnectionBannerController:switchToDefaultInfuraRpc`;
-    handler: NetworkConnectionBannerController['switchToDefaultInfuraRpc'];
+export type NetworkConnectionBannerControllerSwitchToDefaultInfuraRpcEndpointAction = {
+    type: `NetworkConnectionBannerController:switchToDefaultInfuraRpcEndpoint`;
+    handler: NetworkConnectionBannerController['switchToDefaultInfuraRpcEndpoint'];
 };
 /**
  * Union of all NetworkConnectionBannerController action types.
  */
-export type NetworkConnectionBannerControllerMethodActions = NetworkConnectionBannerControllerDismissBannerAction | NetworkConnectionBannerControllerSwitchToDefaultInfuraRpcAction;
+export type NetworkConnectionBannerControllerMethodActions = NetworkConnectionBannerControllerStartAction | NetworkConnectionBannerControllerStopAction | NetworkConnectionBannerControllerDismissBannerAction | NetworkConnectionBannerControllerSwitchToDefaultInfuraRpcEndpointAction;
 //# sourceMappingURL=NetworkConnectionBannerController-method-action-types.d.cts.map

package/dist/NetworkConnectionBannerController-method-action-types.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"NetworkConnectionBannerController-method-action-types.d.cts","sourceRoot":"","sources":["../src/NetworkConnectionBannerController-method-action-types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,iCAAiC,EAAE,gDAA4C;AAE7F;;;;GAIG;AACH,MAAM,MAAM,oDAAoD,GAAG;IACjE,IAAI,EAAE,iDAAiD,CAAC;IACxD,OAAO,EAAE,iCAAiC,CAAC,eAAe,CAAC,CAAC;CAC7D,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,+DAA+D,GAAG;IAC5E,IAAI,EAAE,4DAA4D,CAAC;IACnE,OAAO,EAAE,iCAAiC,CAAC,0BAA0B,CAAC,CAAC;CACxE,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,8CAA8C,GACtD,oDAAoD,GACpD,+DAA+D,CAAC"}
+{"version":3,"file":"NetworkConnectionBannerController-method-action-types.d.cts","sourceRoot":"","sources":["../src/NetworkConnectionBannerController-method-action-types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,iCAAiC,EAAE,gDAA4C;AAE7F;;;;;;;;;GASG;AACH,MAAM,MAAM,4CAA4C,GAAG;IACzD,IAAI,EAAE,yCAAyC,CAAC;IAChD,OAAO,EAAE,iCAAiC,CAAC,OAAO,CAAC,CAAC;CACrD,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,2CAA2C,GAAG;IACxD,IAAI,EAAE,wCAAwC,CAAC;IAC/C,OAAO,EAAE,iCAAiC,CAAC,MAAM,CAAC,CAAC;CACpD,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,oDAAoD,GAAG;IACjE,IAAI,EAAE,iDAAiD,CAAC;IACxD,OAAO,EAAE,iCAAiC,CAAC,eAAe,CAAC,CAAC;CAC7D,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,uEAAuE,GACjF;IACE,IAAI,EAAE,oEAAoE,CAAC;IAC3E,OAAO,EAAE,iCAAiC,CAAC,kCAAkC,CAAC,CAAC;CAChF,CAAC;AAEJ;;GAEG;AACH,MAAM,MAAM,8CAA8C,GACtD,4CAA4C,GAC5C,2CAA2C,GAC3C,oDAAoD,GACpD,uEAAuE,CAAC"}

package/dist/NetworkConnectionBannerController-method-action-types.d.mts

@@ -4,29 +4,49 @@
  */
 import type { NetworkConnectionBannerController } from "./NetworkConnectionBannerController.mjs";
 /**
- * Clears the banner state regardless of the current rule outcome. The next
- * subscription-driven evaluation will re-show the banner if the conditions
- * still hold.
+ * Look for a failed network, if any, and populate the initial state of the
+ * banner. Reacts to upstream state changes from this point on.
+ *
+ * Call this when the wallet UI that consumes the banner becomes active
+ * (typically when the wallet is unlocked and the home surface mounts) so
+ * timers do not run while the user is not looking at the wallet. Should
+ * be called after `NetworkController`, `NetworkEnablementController`, and
+ * `ConnectivityController` have been initialized. Idempotent.
+ */
+export type NetworkConnectionBannerControllerStartAction = {
+    type: `NetworkConnectionBannerController:start`;
+    handler: NetworkConnectionBannerController['start'];
+};
+/**
+ * Stops evaluating network connection state. Clears any pending banner
+ * timers and resets state to `available`. Call this when the UI
+ * consuming the banner is no longer active. Idempotent.
+ */
+export type NetworkConnectionBannerControllerStopAction = {
+    type: `NetworkConnectionBannerController:stop`;
+    handler: NetworkConnectionBannerController['stop'];
+};
+/**
+ * Clears the banner state such that the banner will be hidden.
  */
 export type NetworkConnectionBannerControllerDismissBannerAction = {
     type: `NetworkConnectionBannerController:dismissBanner`;
     handler: NetworkConnectionBannerController['dismissBanner'];
 };
 /**
- * Switches the chain's default RPC endpoint to its first Infura endpoint,
+ * Switches the chain's default RPC endpoint to its Infura endpoint,
  * causing the banner to clear once the network becomes available again.
  *
- * @param args - The arguments to this action.
- * @param args.chainId - The chain whose default RPC should be switched.
+ * @param chainId - The chain whose default RPC endpoint should be switched.
  * @throws If the chain configuration cannot be found, or if it has no
  * Infura endpoint to switch to, or if the default is already Infura.
  */
-export type NetworkConnectionBannerControllerSwitchToDefaultInfuraRpcAction = {
-    type: `NetworkConnectionBannerController:switchToDefaultInfuraRpc`;
-    handler: NetworkConnectionBannerController['switchToDefaultInfuraRpc'];
+export type NetworkConnectionBannerControllerSwitchToDefaultInfuraRpcEndpointAction = {
+    type: `NetworkConnectionBannerController:switchToDefaultInfuraRpcEndpoint`;
+    handler: NetworkConnectionBannerController['switchToDefaultInfuraRpcEndpoint'];
 };
 /**
  * Union of all NetworkConnectionBannerController action types.
  */
-export type NetworkConnectionBannerControllerMethodActions = NetworkConnectionBannerControllerDismissBannerAction | NetworkConnectionBannerControllerSwitchToDefaultInfuraRpcAction;
+export type NetworkConnectionBannerControllerMethodActions = NetworkConnectionBannerControllerStartAction | NetworkConnectionBannerControllerStopAction | NetworkConnectionBannerControllerDismissBannerAction | NetworkConnectionBannerControllerSwitchToDefaultInfuraRpcEndpointAction;
 //# sourceMappingURL=NetworkConnectionBannerController-method-action-types.d.mts.map

package/dist/NetworkConnectionBannerController-method-action-types.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"NetworkConnectionBannerController-method-action-types.d.mts","sourceRoot":"","sources":["../src/NetworkConnectionBannerController-method-action-types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,iCAAiC,EAAE,gDAA4C;AAE7F;;;;GAIG;AACH,MAAM,MAAM,oDAAoD,GAAG;IACjE,IAAI,EAAE,iDAAiD,CAAC;IACxD,OAAO,EAAE,iCAAiC,CAAC,eAAe,CAAC,CAAC;CAC7D,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,+DAA+D,GAAG;IAC5E,IAAI,EAAE,4DAA4D,CAAC;IACnE,OAAO,EAAE,iCAAiC,CAAC,0BAA0B,CAAC,CAAC;CACxE,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,8CAA8C,GACtD,oDAAoD,GACpD,+DAA+D,CAAC"}
+{"version":3,"file":"NetworkConnectionBannerController-method-action-types.d.mts","sourceRoot":"","sources":["../src/NetworkConnectionBannerController-method-action-types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,iCAAiC,EAAE,gDAA4C;AAE7F;;;;;;;;;GASG;AACH,MAAM,MAAM,4CAA4C,GAAG;IACzD,IAAI,EAAE,yCAAyC,CAAC;IAChD,OAAO,EAAE,iCAAiC,CAAC,OAAO,CAAC,CAAC;CACrD,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,2CAA2C,GAAG;IACxD,IAAI,EAAE,wCAAwC,CAAC;IAC/C,OAAO,EAAE,iCAAiC,CAAC,MAAM,CAAC,CAAC;CACpD,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,oDAAoD,GAAG;IACjE,IAAI,EAAE,iDAAiD,CAAC;IACxD,OAAO,EAAE,iCAAiC,CAAC,eAAe,CAAC,CAAC;CAC7D,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,uEAAuE,GACjF;IACE,IAAI,EAAE,oEAAoE,CAAC;IAC3E,OAAO,EAAE,iCAAiC,CAAC,kCAAkC,CAAC,CAAC;CAChF,CAAC;AAEJ;;GAEG;AACH,MAAM,MAAM,8CAA8C,GACtD,4CAA4C,GAC5C,2CAA2C,GAC3C,oDAAoD,GACpD,uEAAuE,CAAC"}

package/dist/NetworkConnectionBannerController-method-action-types.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"NetworkConnectionBannerController-method-action-types.mjs","sourceRoot":"","sources":["../src/NetworkConnectionBannerController-method-action-types.ts"],"names":[],"mappings":"AAAA;;;GAGG","sourcesContent":["/**\n * This file is auto generated.\n * Do not edit manually.\n */\n\nimport type { NetworkConnectionBannerController } from './NetworkConnectionBannerController';\n\n/**\n * Clears the banner state regardless of the current rule outcome. The next\n * subscription-driven evaluation will re-show the banner if the conditions\n * still hold.\n */\nexport type NetworkConnectionBannerControllerDismissBannerAction = {\n  type: `NetworkConnectionBannerController:dismissBanner`;\n  handler: NetworkConnectionBannerController['dismissBanner'];\n};\n\n/**\n * Switches the chain's default RPC endpoint to its first Infura endpoint,\n * causing the banner to clear once the network becomes available again.\n *\n * @param args - The arguments to this action.\n * @param args.chainId - The chain whose default RPC should be switched.\n * @throws If the chain configuration cannot be found, or if it has no\n * Infura endpoint to switch to, or if the default is already Infura.\n */\nexport type NetworkConnectionBannerControllerSwitchToDefaultInfuraRpcAction = {\n  type: `NetworkConnectionBannerController:switchToDefaultInfuraRpc`;\n  handler: NetworkConnectionBannerController['switchToDefaultInfuraRpc'];\n};\n\n/**\n * Union of all NetworkConnectionBannerController action types.\n */\nexport type NetworkConnectionBannerControllerMethodActions =\n  | NetworkConnectionBannerControllerDismissBannerAction\n  | NetworkConnectionBannerControllerSwitchToDefaultInfuraRpcAction;\n"]}
+{"version":3,"file":"NetworkConnectionBannerController-method-action-types.mjs","sourceRoot":"","sources":["../src/NetworkConnectionBannerController-method-action-types.ts"],"names":[],"mappings":"AAAA;;;GAGG","sourcesContent":["/**\n * This file is auto generated.\n * Do not edit manually.\n */\n\nimport type { NetworkConnectionBannerController } from './NetworkConnectionBannerController';\n\n/**\n * Look for a failed network, if any, and populate the initial state of the\n * banner. Reacts to upstream state changes from this point on.\n *\n * Call this when the wallet UI that consumes the banner becomes active\n * (typically when the wallet is unlocked and the home surface mounts) so\n * timers do not run while the user is not looking at the wallet. Should\n * be called after `NetworkController`, `NetworkEnablementController`, and\n * `ConnectivityController` have been initialized. Idempotent.\n */\nexport type NetworkConnectionBannerControllerStartAction = {\n  type: `NetworkConnectionBannerController:start`;\n  handler: NetworkConnectionBannerController['start'];\n};\n\n/**\n * Stops evaluating network connection state. Clears any pending banner\n * timers and resets state to `available`. Call this when the UI\n * consuming the banner is no longer active. Idempotent.\n */\nexport type NetworkConnectionBannerControllerStopAction = {\n  type: `NetworkConnectionBannerController:stop`;\n  handler: NetworkConnectionBannerController['stop'];\n};\n\n/**\n * Clears the banner state such that the banner will be hidden.\n */\nexport type NetworkConnectionBannerControllerDismissBannerAction = {\n  type: `NetworkConnectionBannerController:dismissBanner`;\n  handler: NetworkConnectionBannerController['dismissBanner'];\n};\n\n/**\n * Switches the chain's default RPC endpoint to its Infura endpoint,\n * causing the banner to clear once the network becomes available again.\n *\n * @param chainId - The chain whose default RPC endpoint should be switched.\n * @throws If the chain configuration cannot be found, or if it has no\n * Infura endpoint to switch to, or if the default is already Infura.\n */\nexport type NetworkConnectionBannerControllerSwitchToDefaultInfuraRpcEndpointAction =\n  {\n    type: `NetworkConnectionBannerController:switchToDefaultInfuraRpcEndpoint`;\n    handler: NetworkConnectionBannerController['switchToDefaultInfuraRpcEndpoint'];\n  };\n\n/**\n * Union of all NetworkConnectionBannerController action types.\n */\nexport type NetworkConnectionBannerControllerMethodActions =\n  | NetworkConnectionBannerControllerStartAction\n  | NetworkConnectionBannerControllerStopAction\n  | NetworkConnectionBannerControllerDismissBannerAction\n  | NetworkConnectionBannerControllerSwitchToDefaultInfuraRpcEndpointAction;\n"]}