Class: KeystoreInteraction

interaction.KeystoreInteraction()

Abstract base class for all keystore interactions.

Concrete subclasses will want to subclass either DirectKeystoreInteraction or IndirectKeystoreInteraction.

Defines an API for subclasses to leverage and extend.

  • Subclasses should not have any internal state. External tools (UI frameworks such as React) will maintain state and pass it into the interaction in order to display properly.

  • Subclasses may override the default constructor in order to allow users to pass in parameters.

  • Subclasses should override the messages method to customize what messages are surfaced in applications at what state of the user interface.

  • Subclasses should not try to catch all errors, instead letting them bubble up the stack. This allows UI developers to deal with them as appropriate.

Constructor

new KeystoreInteraction()

Base constructor.

Subclasses will often override this constructor to accept options.

Just make sure to call super() if you do that!

Source:
Example
import {KeystoreInteraction, PENDING, ACTIVE, INFO} from "unchained-wallets";
class DoNothingInteraction extends KeystoreInteraction {

  constructor({param}) {
    super();
    this.param = param;
  }

  messages() {
    const messages = super.messages()
    messages.push({state: PENDING, level: INFO, text: `Interaction pending: ${this.param}` code: "pending"});
    messages.push({state: ACTIVE, level: INFO, text: `Interaction active: ${this.param}` code: "active"});
    return messages;
  }

}

// usage
const interaction = new DoNothingInteraction({param: "foo"});
console.log(interaction.messageTextFor({state: ACTIVE})); // "Interaction active: foo"
console.log(interaction.messageTextFor({state: PENDING})); // "Interaction pending: foo"

Methods

hasMessagesFor(options) → {boolean}

Return whether there are any messages matching the given options.

Parameters:
Name Type Description
options object

options argument

Properties
Name Type Description
state string

must equal this keystore state

level string

must equal this message level

code string | regexp

code must match this regular expression

text string | regexp

text must match this regular expression

version string | regexp

version must match this regular expression

Source:
Returns:
  • whether any messages match the given filters
Type
boolean

isSupported() → {boolean}

Subclasses can override this method to indicate they are not supported.

This method has access to whatever options may have been passed in by the constructor as well as the ability to interact with this.environment to determine whether the functionality is supported. See the Bowser documentation for more details: https://github.com/lancedikson/bowser

Source:
Returns:

whether this interaction is supported

Type
boolean
Example
isSupported() {
  return this.environment.satisfies({
    * declare browsers per OS
    windows: {
      "internet explorer": ">10",
    },
    macos: {
      safari: ">10.1"
    },

    * per platform (mobile, desktop or tablet)
    mobile: {
      safari: '>=9',
      'android browser': '>3.10'
    },

    * or in general
    chrome: "~20.1.1432",
    firefox: ">31",
    opera: ">=22",

    * also supports equality operator
    chrome: "=20.1.1432", * will match particular build only

    * and loose-equality operator
    chrome: "~20",        * will match any 20.* sub-version
    chrome: "~20.1"       * will match any 20.1.* sub-version (20.1.19 as well as 20.1.12.42-alpha.1)
  });
}

messageFor(options) → {module:interaction.Message|null}

Return the first message matching the given options (or null if none is found).

Parameters:
Name Type Description
options object

options argument

Properties
Name Type Description
state string

must equal this keystore state

level string

must equal this message level

code string | regexp

code must match this regular expression

text string | regexp

text must match this regular expression

version string | regexp

version must match this regular expression

Source:
Returns:

the first matching Message object (or null if none is found)

Type
module:interaction.Message | null

messages() → {Array.<module:interaction.Message>}

Return messages array for this interaction.

The messages array is a (possibly empty) array of Message objects.

Subclasses should override this method and add messages as needed. Make sure to call super.messages() to return an empty messages array for you to begin populating.

Source:
Returns:

[]

Type
Array.<module:interaction.Message>

messagesFor(options) → {Array.<module:interaction.Message>}

Return messages filtered by the given options.

Multiple options can be given at once to filter along multiple dimensions.

Parameters:
Name Type Description
options object

options argument

Properties
Name Type Description
state string

must equal this keystore state

level string

must equal this message level

code string | regexp

code must match this regular expression

text string | regexp

text must match this regular expression

version string | regexp

version must match this regular expression

Source:
Returns:

matching Message objects

Type
Array.<module:interaction.Message>
Example
import {PENDING, ACTIVE} from "unchained-bitcoin";
// Create any interaction instance
interaction.messages().forEach(msg => console.log(msg));
  { code: "device.connect", state: "pending", level: "info", text: "Please plug in your device."}
  { code: "device.active", state: "active", level: "info", text: "Communicating with your device..."}
  { code: "device.active.warning", state: "active", level: "warning", text: "Your device will warn you about...", version: "2.x"}
interaction.messagesFor({state: PENDING}).forEach(msg => console.log(msg));
  { code: "device.connect", state: "pending", level: "info", text: "Please plug in your device."}
interaction.messagesFor({code: ACTIVE}).forEach(msg => console.log(msg));
  { code: "device.active", state: "active", level: "info", text: "Communicating with your device..."}
  { code: "device.active.warning", state: "active", level: "warning", text: "Your device will warn you about...", version: "2.x"}
interaction.messagesFor({version: /^2/}).forEach(msg => console.log(msg));
  { code: "device.active", state: "active", level: "warning", text: "Your device will warn you about...", version: "2.x"}

messageTextFor(options) → {string|null}

Retrieve the text of the first message matching the given options (or null if none is found).

Parameters:
Name Type Description
options object

options argument

Properties
Name Type Description
state string

must equal this keystore state

level string

must equal this message level

code string | regexp

code must match this regular expression

text string | regexp

text must match this regular expression

version string | regexp

version must match this regular expression

Source:
Returns:

the text of the first matching message (or null if none is found)

Type
string | null