.. target audience: core developer

Nexus API
###########

.. contents:: Table of Contents

HTTP API
========

In the current version, the API calls are only available to
the superuser, when no authorization condition is explictly stated.

Configuration
-------------


Returns configuration values currently used by Nexus.
This call is unauthenticated.

.. http:get:: {nexusBase}/config

  **Response:**

  .. ts:def:: ConfigResponse

     interface ConfigResponse {

       // nexus version, X.Y.Z format.
       version: string;
     }


Authentication
--------------

Currently every request made to nexus must be authenticated using the *HTTP
basic auth* mechanism.

Other authentication mechanisms (e.g. OpenID Connect) might
be supported in the future.

User Management
---------------

.. http:get:: {nexusBase}/user

  Get information about the current user.  The username carried
  along the HTTP basic auth points at the user to be shown.

  **Response:**

  .. ts:def:: GetUserResponse

     interface UserResponse {

       // User name
       username: string;

       // Is this a super user?
       superuser: Boolean;
     }

.. http:post:: {nexusBase}/users/{userName}/password

  Change password of the ``{userName}`` user.  The call is
  available to any superuser on any username.

  **Request:**

  .. code-block:: ts

    interface UserChangePassword {
      newPassword: string;
    }

  **Response:**

  :http:statuscode:`200 OK`: The password was successfully changeD.


.. http:post:: {nexusBase}/users

  Create a new user.  Only a superuser can call this API.

  **Request:**

  The body is a `User` object.

  **Response:**

  :http:statuscode:`409 Conflict`: Username is not available.

  **Details:**

  .. ts:def:: User

     interface User {

       // User name
       username: string;

       // Initial password
       password: string;
     }


.. http:get:: {nexusBase}/users

  Return the list of all users.

  **Response:**

  .. ts:def:: UsersResponse

     interface UsersResponse {
       users: UserResponse[];
     }

.. _nexus-permissions-api:

Permissions API
---------------

The permissions API manages authorization of access of subjects
(usually users) to resources.

Permissions are modeled a set of ``(subject, resource, permission)``
triples.  Subjects and resources consist of a type and an identifier.

Superusers are not subject to further permission checks, they are
allowed to do any operation.

The following subject types are currently supported:

* ``user``:  An authenticated user.  The subject ID
  is interpreted as the user ID.

The following permissions are currently defined:

* ``facade.talerWireGateway.history``:  Allows querying the
  transaction history through a Taler wire gateway facade.
* ``facade.talerWireGateway.transfer``: Allows creating payment
  initiations to transfer money via a Taler wire gateway facade.

The following resource IDs are currently supported:

* ``facade``: A LibEuFin facade.  The resource ID is interpreted
  as the facade name.

* ``bank-account``: A Nexus bank account, currently used in
  `scheduled tasks <nexus-task_>`_ of type ``fetch`` and ``submit``.

.. http:get:: {nexusbase}/permissions

   Lists all permissions.

   **Response**

  .. ts:def:: QueryPermissionsResponse

     interface QueryPermissionsResponse {
       permissions: LibeufinPermission[];
     }

.. http:post:: {nexusbase}/permissions

   Modifies permissions.

   **Request**

  .. ts:def:: QueryPermissionsResponse

     interface QueryPermissionsResponse {
       action: "grant" | "revoke";
       permission: LibeufinPermission;
     }

   **Response**

   The response is an empty JSON object.


Test API
--------

.. http:post:: {nexusbase}/bank-accounts/{acctid}/test-camt-ingestion/{type}

  This call allows tests to **directly** give Nexus a Camt document.  After
  the processing, all the payment(s) details should be ingested as if the
  Camt came normally from a bank / the Sandbox.  ``acctid`` must match the
  label of a locally imported bank account, and ``type`` for now can only be
  ``C53``.

  **Response**

  The successful case should respond with a ``200 OK`` and an empty JSON body.

Bank Accounts
-------------

Neuxs maintains a copy of the bank account transaction history and
balance information, manages payment initiations of the account and
tracks the initiations of payments.

.. http:get:: {nexusBase}/bank-accounts

  **Response:**

  A list of `BankAccount` objects that belong to the requester.
  The list is held in the ``accounts`` field.

  .. ts:def:: BankAccount

     interface BankAccount {
       // mnemonic name identifying this bank account.
       nexusBankAccountId: string;
       // IBAN
       iban: string;
       // BIC
       bic: string;
       // Legal subject owning the account.
       ownerName: string;
     }


.. http:get:: {nexusBase}/bank-accounts/{my-acct}

   Get basic information about the bank account named ``my-acct``.

   .. ts:def:: BankAccountInfoWithBalance

     interface BankAccountInfoWithBalance {
       // ID number of the database row being the default bank connection
       // of ``my-acct``.
       defaultBankConnection: number;
       // Payto://-URI of ``my-acct``.
       accountPaytoUri: string;
       // Balance of ``my-acct`` as it was downloaded from the bank
       // along the last Camt document.  A human-readable message
       // will inform the requester, should this value not be found.
       lastSeenBalance: string;
     }

.. http:post:: {nexusBase}/bank-accounts/{acctid}/payment-initiations/{pmtid}/submit

  Asks nexus to submit one prepare payment at the bank.

  :http:statuscode:`404 Not found`: the unique identifier **or**
  the bank connection could not be found in the system


.. http:get:: {nexus}/bank-accounts/{my-acct}/payment-initiations/{uuid}

   Asks the status of payment ``$uuid``.

   **Response:**

   .. ts:def:: PaymentStatus

      interface PaymentStatus {
        // Can be "BOOK" or "PDNG" ('pending').
        status: string;

        // Payment unique identifier
        paymentInitiationId: string;

        // True for submitted payments
        submitted: boolean;

        // Creditor IBAN
        creditorIban: string;

        // Creditor BIC
        creditorBic: string;

        // Creditor legal name
        creditorName: string;

        // Amount
        amount: string;

        // Subject
        subject: string;

        // Date of submission (in dashed form YYYY-MM-DD)
        submissionDate: string;

        // Date of preparation (in dashed form YYYY-MM-DD)
        preparationDate: string;
      }

.. http:get:: {nexusBase}/bank-accounts/{my-acct}/payment-initiations

  Asks nexus the list of initiated payments.  At this stage of the API,
  **all** is returned: submitted and non-submitted payments.

  **Response**

  .. ts:def:: InitiatedPayments

     interface InitiatedPayments {

       // list of all the initiated payments' UID.
       initiatedPayments: PaymentStatus[];
     }


.. http:post:: {nexusBase}/bank-accounts/{my-acct}/payment-initiations

  Ask nexus to prepare instructions for a new payment.
  Note that ``my-acct`` is the bank account that will be
  **debited** after this operation.

  **Request:**

  .. ts:def:: PreparedPaymentRequest

     interface PreparedPaymentRequest {
       // IBAN that will receive the payment.
       iban: string;
       // BIC hosting the IBAN.
       bic: string;
       // Legal subject that will receive the payment.
       name: string;
       // payment subject.
       subject: string;
       // amount, in the format CURRENCY:XX.YY
       amount: string
     }

  **Response:**

  .. ts:def:: PreparedPaymentResponse

     interface PreparedPaymentResponse {

       // Opaque identifier to be communicated when
       // the user wants to submit the payment to the
       // bank.
       uuid: string;
     }

.. http:post:: {nexusBase}/bank-accounts/{acctid}/fetch-transactions

  Nexus will download bank transactions using the given connection.

  **Request:**

  Refer to :ref:`FetchParams <fetch-params>` for
  ``level`` and ``rangeType`` specifications.

  .. ts:def:: CollectedTransaction

     interface CollectedTransaction {
         level: string;
         rangeType: string;
         // Bank connection to use.  Uses the default bank connection,
         // when not given.
         bankConnection: string?;
     }

  **Response:**

  .. code-block:: ts

    interface NewTransactions {
      // How many transactions are new to Nexus.
      newTransactions: number;
      // How many transactions got downloaded by the request.
      // Note that a transaction can be downloaded multiple
      // times but only counts as new once.
      downloadedTransactions: number;
    }

  :http:statuscode:`500 Internal Server Error`: Nexus itself had a problem
  along the operation, and not the bank.


.. http:get:: {nexusBase}/bank-accounts/{acctid}/transactions

  Shows all the transactions fetched for ``{acctid}``.

  **Query parameters:**

  **Response:** A object with a unique field named ``transactions``
  that contains a list of `Transaction` objects.

  .. ts:def:: Transaction

     interface Transaction {

       // money moved by the transaction
       amount: string;

       // CRDT or DBIT
       creditDebitIndicator: string

       // Two of the most used values are BOOK, or PENDING
       status: string;

       // FIXME
       bankTransactionCode: string;

       // FIXME
       valueDate: string;

       // When this payment got booked.  In the form YYYY-MM-DD
       bookingDate: string;

       // FIXME
       accountServicerRef: string;

       // FIXME
       batches: {
         // list of batched transactions
         batchTransactions: BatchedTransaction[];
       };
     }

  .. ts:def:: BatchedTransaction

     interface BatchedTransaction {
       // FIXME
       amount: string;
       // FIXME
       creditDebitIndicator: string;
       // FIXME
       details {
         debtor: {
           name: string;
         };
         debtorAccount: {
           iban: string;
         };
         // Missing, when the payment is DBIT.
         debtorAgent: {
           bic: string;
         };
         creditor: {
           name: string;
         };
         creditorAccount: {
           iban: string;
         };
         // Missing, when the payment is CRDT.
         creditorAgent: {
           iban: string;
         };
         // FIXME
         endToEndId: string;
         // FIXME
         unstructuredRemittanceInformation: string;
       }
     }

Scheduling API
--------------

.. http:post:: {nexusBase}/bank-accounts/{acctid}/schedule

  This endpoint allows the caller to define a recurrent
  execution of a task.

  **Request**

  .. ts:def:: ScheduleTask

    interface ScheduleTask {
      // Name to assign to the task being created.
      name: string;

      // a Unix-compatible cron pattern representing
      // the frequency of execution of this task.
      cronspec: string;

      // Can take values "fetch" (to download the history
      // of the requester's bank account) or "submit" (to submit
      // any initiated payment associated to the requester's
      // bank account).
      type: string;

      // Currently only used for "fetch" operations but required
      // for any type of task.  Whatever value "submit" tasks pass
      // here, it is not going to be consumed by Nexus.  Typically,
      // submit tasks pass FetchParams with all of its fields set
      // as null.
      params: FetchParams;
    }


.. http:get:: {nexusBase}/bank-accounts/{acctid}/schedule/{taskId}

  Shows ``taskId`` state.

  .. _nexus-task:

  **Response**

  .. ts:def:: NexusTask

     // This object is a mere reflection of
     // what the Nexus database keeps to implement
     // the scheduling feature.

     interface NexusTask {
       // The resource being impacted by this operation.
       // Typically a (Nexus) bank account being ``fetch``ed
       // or whose payments are ``submit``ted.  In this cases,
       // this value is the "bank-account" constant.
       resourceType: string;
       // Name of the resource.  In case of "bank-account", that
       // is the name under which the bank account was imported
       // from the bank.
       resourceId: string;
       // Task name, equals 'taskId'
       taskName: string;
       // Values allowed are "fetch" or "submit".
       taskType: string;
       // FIXME: describe.
       taskCronSpec: string;
       // Only meaningful for "fetch" types.
       taskParams: FetchParams;
       // Timestamp in secons when the next iteration will run.
       nextScheduledExecutionSec: number;
       // Timestamp in seconds when the previous iteration ran.
       prevScheduledExecutionSec: number;
     }


.. http:delete:: {nexusBase}/bank-accounts/{acctid}/schedule/{taskId}

  This call deletes the task associated to ``taskId``.

.. http:get:: {nexusBase}/bank-accounts/{acctid}/schedule

   Shows all the scheduled tasks from ``acctid``.

  **Response**

  .. ts:def:: TaskCollection

    interface TaskCollection {

      // This field can contain *multiple* objects of the type sampled below.
      schedule: {

        'task-name': {
          cronspec: string;
          type: "fetch" | "submit";
          params: FetchParams;
        }
      }
    }


Bank Connections
----------------

Bank connections connect the local Nexus bank account to the bank.

.. http:post:: <nexus>/bank-connections

  Activate a new bank connection for the requesting user.

  **Request:**

  This request can accept two formats, depending on whether a
  new bank connection is being made, or a connection backup is
  being restored.


  This type allows the creation of new bank accounts.

  .. _new-conn:

  .. ts:def:: NewBankConnection

     interface NewBankConnection {

       source: string; // only "new" allowed

       // connection name.
       name: string;

       // type of the connection to make: "ebics" for example.
       type: string;

       // Strictly dependent from the connection type.
       data: any;
     }

  This type allows to restore a previously made bank connection.

  .. _restore-conn:

  .. ts:def:: BankConnectionRestore

     interface BankConnectionRestore {

       source: "backup";

       // connection name.
       name: string;

       // Backup data, as typically returned by the
       // "../export-backup" API.
       backup: any;

       passphrase?: string;
     }

  The following examples show the EBICS types for creating and
  restoring a connection.

  This type is found in the ``data`` field of `NewBankConnection <new-conn_>`_.

  .. _ebics-new-conn:

  .. ts:def:: EbicsNewConnection

    interface EbicsNewConnection {
      userID: string,
      partnerID: string,
      hostID: string,
      ebicsURL: string,
      systemID?: string
    }

  This type is found in the ``backup`` field of `BankConnectionRestore <restore-conn_>`_.

  .. ts:def:: EbicsBackup

    interface EbicsBackup {
      type: string, // constant to "ebics"
      userID: string,
      partnerID: string,
      hostID: string,
      ebicsURL: string,

      // The following three values are the EBICS private keys.
      authBlob: string,
      encBlob: string,
      sigBlob: string
    }

  **Response:**

  :http:statuscode:`406 Not acceptable`: a connection with the
  requested name already exists for this user.

.. http:post:: {nexusBase}/bank-connections/delete-connection

  **Request:**

  .. ts:def:: BankConnectionDeletion

      interface BankConnectionDeletion {
        // label of the bank connection to delete
        bankConnectionId: string;
      }

.. http:get:: {nexusBase}/bank-connections

   List available bank connections.

   **Response**

   A JSON object whose ``bankConnections`` element is a list of the following type:

   .. ts:def:: BankConnection

       interface BankConnection {

         // connection type.  For example "ebics".
         type: string;

         // connection name as given by the user at
         // the moment of creation.
         name: string;
       }


.. http:get:: {nexusBase}/bank-connections/{connId}

   Get information about one bank connection.

   .. ts:def:: BankConnectionInfo

      interface BankConnectionInfo {
        type: string;
        owner: string;
        // if true, this connection can be used to communicate
        // with the bank.
        ready: boolean;
        // Depends on the type.
        details: any;
      }

   For example, the following type occupies the ``details``
   field for EBICS connections.

   .. ts:def:: EbicsConnectionInfo

     interface EbicsConnectionInfo {
       ebicsUrl: string;
       ebicsHostId: string;
       partnerId: string;
       userId: string;
     }

.. http:post:: {nexusBase}/bank-connections/{connId}/connect

   Initialize the connection by talking to the bank.  For EBICS
   connections, this endpoint causes Nexus to submit its own keys
   and download the bank's.  That however **still** requires the
   user to send the public keys to the bank via post, in order
   to start operating.

.. http:post:: {nexusBase}/bank-connections/{connId}/export-backup

   Make a passphrase-encrypted backup of this connection.

.. http:post:: {nexusBase}/bank-connections/{connId}/fetch-accounts

   Update accounts that are accessible via this bank connection.
   After this operation, Nexus has stored the names of each bank
   account, under ``connId``, that the bank communicated.

   Note: after this operation, Nexus **still** needs to
   `assign each bank account a local name <import-account_>`_ ,
   in order to start operating.

.. _import-account:

.. http:post:: {nexusBase}/bank-connections/{connId}/import-account

  Import a bank account provided by the connection into the Nexus.
  This operation assigns a local name to one bank account that was
  downloaded from the bank.

  If no Nexus bank account with the ID ``nexusBankAccountId`` exists,
  a new one will be created, and it will have ``connId`` as the
  default bank connection.

  If an existing local bank account whose ID equals ``nexusBankAccountId``
  already exists, this call fails if ``offeredAccountId`` and ``nexusBankAccountId``
  have different IBANs.  If instead the IBAN is the same, this call merely
  associates ``offeredAccountId`` to ``nexusBankAccountId`` internally
  in the database without changing ``nexusBankAccountId`` default connection.

  .. ts:def:: ImportBankAccount

     interface ImportBankAccount {

       // Identifier for the bank account, as returned by /accounts
       // of the bank connection.
       offeredAccountId: string;

       // Nexus-local identifier for the bank account.
       nexusBankAccountId: string;
     }

  **Response:**

  :http:statuscode:`409 Conflict`: ``nexusBankAccountId`` exists already but
  its IBAN is different from the one carried by ``offeredAccountId``.

.. http:get:: {nexusBase}/bank-connections/{connId}/accounts

  List the bank accounts that this bank connection provides access to.

  **Response:**

  The response is a JSON object whose ``accounts`` field is a list of the
  following type.

  .. ts:def:: OfferedBankAccount

     interface OfferedBankAccount {

       // Unique identifier for the offered account
       offeredAccountId: string;

       // IBAN of the offered account
       iban: string;

       // BIC of the account's financial institution
       bic: string;

       // Account owner name
       ownerName: string;

       // If the account has been imported,
       // this field contains the ID of the
       // Nexus bank account associated with it,
       // null otherwise.
       nexusBankAccountId: string | null;
     }


.. http:get:: <nexus>/bank-connections/{connId}/messages

  List *some* details of all the ISO2022 messages gotten from
  the bank.

  **Response:**

  The response is a JSON object whose ``bankMessages`` field
  is a list of the following type.

  .. code-block:: ts

    interface BankMessageInfo {

      // the message type, typically how the containing layer
      // (Ebics, for example) would label this information.  For
      // Camt.053 types, this value is "C53".
      code: string;

      // the unique identifier of the message.
      messageId: string;

      // bytes length of the message.
      length: number;
    }

.. http:get:: <nexus>/bank-connections/{connId}/messages/{msgId}

  Return the ISO20022 XML corresponding to ``msgId``.


Facades
-------

.. http:get:: <nexus>/facades/{fcid}

   **Response:** A `FacadeShowInfo` whose name is ``fcid``.

.. http:get:: <nexus>/facades

  List available facades that belong to the requesting user.

  **Response:**  A list of the following elements:

.. ts:def:: FacadeShowInfo

    interface FacadeShowInfo {

      // Name of the facade, same as the "fcid" parameter.
      name: string;

      // Type of the facade.
      // For example, "taler-wire-gateway".
      type: string;

      // Bas URL of the facade.
      baseUrl: string;

      // details depending on the facade type.
      config: any;
    }

  For "taler-wire-gateway" and "anastasis" facades,
  ``config`` contains the following type:

  .. ts:def:: TalerAnastasisFacadeState

    interface TalerFacadeState {
      // Bank connection this facade relies on.
      bankConnection: string;
      // (Nexus local) bank account associated to this facade.
      bankAccount: string;
      // Whether the facade seeks reports or statements from the bank.
      reserveTransferLevel?: string;
      currency?: string;
    }

.. http:delete:: {nexus}/facades/{fcid}

  Deletes a facade.

.. http:post:: {nexus}/facades

  Creates a new facade.

  **Request:**

  .. code-block:: ts

     interface FacadeInfo {
        // Name of the facade, same as the "fcid" parameter.
        name: string;

        // Type of the facade.
        // For example, "taler-wire-gateway" or "anastasis".
        type: string;

        // Bank accounts that the facade has read/write access to.
        bankAccountsRead?: string[];
        bankAccountsWrite?: string[];

        // Bank connections that the facade has read/write access to.
        bankConnectionsRead?: string[];
        bankConnectionsWrite?: string[];

        // Facade-specific configuration details.  Only the
        // following type is available.
        config: TalerAnastasisFacadeState;
     }

Bank Connection Protocols
-------------------------

.. http:get:: {nexus}/bank-connection-protocols

   Lists supported bank connection protocols.

.. http:post:: {nexus}/bank-connection-protocols/ebics/test-host

   Check if Nexus can talk to an EBICS host.
   This doesn't create a new connection in the database,
   and is useful during setup when the user hasn't entered
   the full details for the connection yet.

   .. ts:def:: EbicsHostTestRequest

      interface EbicsHostTestRequest {
        ebicsBaseUrl: string;
        ebicsHostId: string;
      }


EBICS-specific APIs
-------------------

The following endpoints are only available for EBICS bank connections.
They are namespaced under the ``/ebics/`` sub-resource.

.. http:post:: {nexusBase}/bank-connections/{connection-name}/ebics/download/{msg}

  .. warning::

    Use with care.  Typically only necessary for testing and debugging.

  Perform an EBICS download transaction of type ``msg``.
  This request will not affect any bank account or other state
  in Nexus database.  It will just make a request to the bank
  and return the answer.

Anastasis API.
--------------

This is a read-only API offering a view over *only* the incoming
transactions of a bank account.  The name comes from the use in
`Anastasis <https://www.anastasis.lu>`_.

.. http:get:: ${BASE_URL}/history/incoming

  Returns a list of transactions made to the customer.

  Transactions are identified by a numeric identifier,
  that reflects the order in which Nexus downloaded each
  transaction from the bank.

  The list of returned transactions is determined by a row
  ID *starting point* and a signed non-zero integer *delta*:

  * If *delta* is positive, returns a list of up to *delta*
    transactions (all matching the filter criteria) strictly
    **after** the starting point.  The transactions are sorted
    in **ascending** order of the row ID.
  * If *delta* is negative, return a list of up to *-delta*
    transactions (all matching the filter criteria) strictly
    **before** the starting point.  The transactions are sorted
    in **descending** order of the row ID.

  If *starting point* is not explicitly given, it defaults to:

  * A value that is **smaller** than all other row IDs if *delta*
    is **positive**.
  * A value that is **larger** than all other row IDs if *delta*
    is **negative**.

  **Request**

  :query start: *Optional.*
    Row identifier to explicitly set the *starting point* of the query.
  :query delta:
    The *delta* value that determines the range of the query.
  :query long_poll_ms: *Optional.*  If this parameter is specified and the
    result of the query would be empty, Nexus will wait up to ``long_poll_ms``
    milliseconds for new transactions that match the query to arrive and only
    then send the HTTP response.  A client must never rely on this behavior, as
    Nexus may return a response immediately or after waiting only a fraction
    of ``long_poll_ms``.

  **Response**

  :http:statuscode:`200 OK`: JSON object of type `IncomingHistory`.

  :http:statuscode:`400 Bad request`: Request malformed. Nexus replies
  with an `ErrorDetail` object.

  :http:statuscode:`401 Unauthorized`: Authentication failed, likely
  the credentials are wrong.

  :http:statuscode:`404 Not found`: The endpoint is wrong or the user
  name is unknown. Nexus replies with an `ErrorDetail` object.

  .. ts:def:: IncomingHistory

    interface IncomingHistory {

      // Array of incoming transactions.
      incoming_transactions : IncomingBankTransaction[];

    }

  .. ts:def:: IncomingBankTransaction

    interface IncomingBankTransaction {

      // Opaque identifier of the returned record.
      row_id: SafeUint64;

      // Date of the transaction.
      date: Timestamp;

      // Amount transferred.
      amount: Amount;

      // Payto URI to identify the receiver of funds.
      // Typically an exchange's bank accounts.
      credit_account: string;

      // Payto URI to identify the sender of funds.
      debit_account: string;

      // subject of the incoming payment.
      subject: string;
    }

Reaching the facade
-------------------

Once a facade with name ``fcid`` and type ``ftype`` has been
created, all its endpoints become offered by the following base
URL:

.. code-block:: console

   $NEXUS_URL/facades/$fcid/$ftype

For example, a ``taler-wire-gateway`` facade named ``foo`` will
offer its endpoints under

.. code-block:: console

   https://nexus.example.com/facades/foo/taler-wire-gateway/