Nexus How-To
############

.. contents:: Table of Contents

Nexus is a Web service that provides a JSON abstraction layer to
access bank accounts.  It is **not** itself a bank, but a translator
between JSON requests and more structured banking protocols (like
EBICS, for example.), that are offered by actual banks.

This document explains how to setup Nexus to access a bank account
via the EBICS protocol.  In order to follow all the steps below, the
reader should already have one EBICS subscriber activated at their bank.

Obtain Nexus
============
Nexus belongs to the LibEuFin project, and can be downloaded via Git:
``$ git clone git://git.taler.net/libeufin``

Note that Kotlin+Gradle should already work on the host system.

Install Nexus
=============
Navigate into the `libeufin` local repository, and from top-level run:

.. code-block:: shell

  $ ./gradlew -Pprefix=$PREFIX nexus:installToPrefix
  $ ./gradlew -Pprefix=$PREFIX cli:installToPrefix

In case of success, the two following commands should be found:

.. code-block:: shell

  $ which libeufin-nexus
  $ which libeufin-cli

Connect Nexus with a EBICS account
==================================

Use the following command to *(1) run the nexus service*:

.. code-block:: shell

  $ libeufin-nexus

At this point a *(2) superuser account needs to be activated
into the system*:

.. code-block:: shell

  $ libeufin-nexus superuser foo # Will interactively ask for password

For simplicity, we'll enable the superuser to access the bank account
via the EBICS protocol, but a API to create less privileged users is
as well offered.

Nexus needs now to associate the user to a EBICS subscriber that was
activated on the bank.  In the Nexus terminology, this is called *(3)
creating a EBICS connection*.

.. code-block:: shell

  libeufin-cli \
    connections \
      new-ebics-connection \
        --connection-name $NEXUS_BANK_CONNECTION_NAME \
        --ebics-url $EBICS_BASE_URL \
        --host-id $EBICS_HOST_ID \
        --partner-id $EBICS_PARTNER_ID \
        --ebics-user-id $EBICS_USER_ID \
        --nexus-user-id $NEXUS_USER \
        --nexus-password $NEXUS_PASSWORD \
        $NEXUS_URL

If the previous command succeeded, Nexus must communicate all the details
to the bank.  Therefore, it will *(4) synchronize the connection*.

.. code-block:: shell

  libeufin-cli \
    connections \
      sync \
        --connection-name $NEXUS_BANK_CONNECTION_NAME \
        --nexus-user-id $NEXUS_USER \
        --nexus-password $NEXUS_PASSWORD \
        $NEXUS_URL

Once the connection is synchronized, Nexus needs to import locally the data
corresponding to the bank accounts offered by the bank connection just made.
The command below *(5) downloads the list of the bank accounts offered by the*
``$NEXUS_BANK_CONNECTION_NAME``.

.. code-block:: shell

  libeufin-cli \
    connections \
      download-bank-accounts \
        --connection-name $NEXUS_BANK_CONNECTION_NAME \
        --nexus-user-id $NEXUS_USER \
        --nexus-password $NEXUS_PASSWORD \
        $NEXUS_URL

It is now possible to *(6) list the accounts offered by the connection*.

.. code-block:: shell

  libeufin-cli \
    connections \
      list-offered-bank-accounts \
        --nexus-user-id $NEXUS_USER \
        --nexus-password $NEXUS_PASSWORD \
        $NEXUS_URL

Nexus now needs an explicit *(7) import of the accounts it needs to manage*.
This step is needed to let the user pick a custom name for such accounts.

.. code-block:: shell

  libeufin-cli
    connections \
      import-bank-account \
        --connection-name $NEXUS_BANK_CONNECTION_NAME \
        --nexus-user-id $NEXUS_USER \
        --nexus-password $NEXUS_PASSWORD \
        --offered-account-id $ACCOUNT_NATIVE_NAME \
        --nexus-bank-account-id $CUSTOM_RENAMING_FOR_ACCOUNT \
        $NEXUS_URL

Once a Nexus user imported a bank account (``$CUSTOM_RENAMING_FOR_ACCOUNT``)
under a certain connection (``$NEXUS_BANK_CONNECTION_NAME``), it is possible
to accomplish the usual operations for any bank account: asking for the
list of transactions, and making a payment.

Request history of transactions
===============================

It is first needed to tell Nexus to download the latest news
from the bank, and then ask it again to return the results.

This command asks Nexus to *download the latest bank statements*:

.. code-block:: shell

  libeufin-cli \
    accounts \
      fetch-transactions \
        --nexus-user-id $NEXUS_USER \
        --nexus-password $NEXUS_PASSWORD \
        --account-name $CUSTOM_RENAMING_FOR_ACCOUNT \
        $NEXUS_URL

Once Nexus stored all the information in the database, the
client can ask to actually **see** the transactions:

.. code-block:: shell

  libeufin-cli
    accounts \
      transactions \
        --nexus-user-id $NEXUS_USER \
        --nexus-password $NEXUS_PASSWORD \
        --account-name $CUSTOM_RENAMING_FOR_ACCOUNT \
        $NEXUS_URL

Make a payment
==============

TBD.