npm package: @privacybydesign/irma-core
Description: The state machine for implementing IRMA flows, that plugins can register on
Latest version: 0.4.3
Deprecated: Please use the Yivi frontend packages instead, see: https://github.com/privacybydesign/yivi-frontend-packages

# IRMA core

This package contains the state machine for implementing IRMA flows. `irma-core`
itself does not provide any real functionality. Plugins can be registered at
the state machine and the plugins then provide the functionality depending on
the state the state machine is in. The plugins can also request state modifications
to the state machine.
                                                                     
IRMA core can be initialized in the following way:

```javascript
const IrmaCore = require('@privacybydesign/irma-core');
const irma     = new IrmaCore(/* options */);

irma.use(/* Plugin A */);
irma.use(/* Plugin B */);

irma.start();
```

You can pass an options object to the constructor, which will be passed on to
each plugin that you register. Each plugin can choose which of your options to
use or ignore.

```javascript
const irma = new IrmaCore({
  debugging: true,            // Used by state machine and multiple plugins
  element:   '#irma-web-form' // Used by `irma-web` plugin
});
```

## Documentation
More elaborate documentation on how to use this module can be found in the
[IRMA documentation](https://irma.app/docs/irma-frontend/#irma-core). You
can also find here how to [design your own plugin](https://irma.app/docs/irma-frontend/#make-your-own-irma-core-plugin).

## API
### `use` method
With the `use` method, new plugins can be added to the IRMA core instance.
This method takes care of instantiating the plugin. You simply pass the
plugin class as an argument to this function; you must not instantiate
the plugin yourself.

```javascript
irma.use(/* Plugin A */);
irma.use(/* Plugin B */);
```

### `start` method
The `start` method starts the state machine and returns a Promise. Whatever
parameters you pass to the `start` method get passed to the `start` method of
the plugins too, but no plugins currently make use of that.

```javascript
irma.start()
    .then(result => console.log("Successful disclosure! 🎉", result))
    .catch(error => console.error("Couldn't do what you asked 😢", error));
```

The returned Promise only resolves when the state machine reaches the `Success` state
and only rejects when the machine reaches a state with a final transaction.
The end states `BrowserNotSupported` and `Aborted` always lead to a reject.
The other possible end states are `Cancelled`, `Timeout` and `Error`.

In case none of the plugins supplied a return value via its
`close()` method (which is the case for all our plugins in the `/plugin` directory),
the return value on resolve will be the payload of the 'succeed' transition.
In case of reject, the return value indicates in what state the state machine stopped,
so: `BrowserNotSupported`, `Cancelled`, `Timeout`, `Error` or `Aborted`.

In case one or more plugins return a value on `close()`, the return value will be
an array containing the `irma-core` return value (as described above) as first item
and the return values of the plugins as subsequent items. The order of the
subsequent items is determined by the order in which the plugins were
added with 'use'. Plugins that did not return a value, have the result
`undefined` then.

```javascript
irma.start()
    .then(result => console.log("Successful disclosure! 🎉", result))
    .catch(error => {
          if (error === 'Aborted') {
            console.log('We closed it ourselves, so no problem 😅');
            return;
          }
          console.error("Couldn't do what you asked 😢", error);
    });
```

In the reject case, plugins may already inform the user of this issue, so please
test if you need to catch the state yourself. You may wish to fall back to
another authentication method automatically by catching the rejection and
redirecting the user.

### `abort` method
The `abort` method forces an `irma-core` instance to abort the session and
all associated plugins should stop making changes. In this way you can stop
the instance from being active when it is not relevant anymore. The promise
returned by the `start` method will be rejected with a `Aborted` message
when `abort` is called. When `start` has not been called yet or when the
`start` promise has already finished, then calling `abort` has no effect.

```javascript
irma.abort();
```