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

HTTP API
========

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.

Users Management
----------------

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

  Get information about the current user (based on the authentication information
  in this request).

  **Response:**

  .. ts:def:: GetUserResponse

     interface UserResponse {

       // User name
       username: string;

       // Is it a superuser?
       superuser: boolean;
     }

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

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

  **Request:**

  The body is a `User` object.

  **Response:**

  :status 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 list of users.

Bank Account Management
-----------------------

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

  A list of `BankAccount` objects
  that belong to the requester.

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

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

  Ask nexus to submit one prepare payment at the bank.

  :status 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}
   
   Ask the status of payment ``$uuid``.

   **Response:**

   .. ts:def:: PaymentStatus

      interface PaymentStatus {

        // Payment unique identifier
        uuid: 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: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:**

  .. ts:def:: CollectedTransaction

     interface CollectedTransaction {
       // Optional field to specify the bank connection to
       // use for such operation.
       bankConnection?: string;
       // dashed date (YYYY-MM-DD) of the earliest payment
       // in the result. Optional, defaults to "earliest
       // possible" date.
       start: string;
       // dashed date (YYYY-MM-DD) of the earliest payment
       // in the result. Optional, defaults to "latest
       // possible" date.
       end: string;
     }

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

  Shows which transactions are stored locally at nexus.

  **Query parameters:**

  * **start** start (dashed YYYY-MM-DD) date of desired payments.
    Optional, defaults to "earliest possible" date
  * **end** end (dashed YYYY-MM-DD) date of desired payments.
    Optional, defaults to "earliest possible" date


  **Response:** A list of `Transaction` objects.

  .. ts:def:: Transaction

     interface Transaction {
       // local bank account involved in the transaction.
       account: string;

       // counterpart IBAN
       counterpartIban: string;

       // counterpart BIC
       counterpartBic: string;

       // counterpart holder name
       counterpartName: string;

       // amount, in the format [-]CURRENCY:XX.YY,
       // where the minus sign as prefix indicates
       // a debit for the user's bank account.
       amount: string;

       // Dashed date YYYY-MM(01-12)-DD(01-31) of the transaction.
       date: string;

       // Payment subject.
       subject: string;
     }


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

Bank connections connect the local LibEuFin bank account
to the real bank.

.. http:post:: <nexus>/bank-connections
  
  Activate a new bank connection for the requesting user.

  **Request:**

  .. ts:def:: BankConnectionRestoreRequest

     interface BankConnectionRestoreRequest {

       source: "new" | "backup";

       name: string;

       // Restore a previous connection.  Take precedence
       // over the 'new' field.
       backup?: BankConnectionBackup;

       passphrase?: string;
       
       // Data to create a fresh bank connection without
       // restoring any backup.
       data?: BankConnectionNew;
     }


  .. ts:def:: ConnectionNew

     interface ConnectionNew {

       // This type is strictly dependent on
       // the connection being created.  For Ebics,
       // it will contain the required fields (as strings):
       // 'ebicsURL', 'userID', 'partnerID', 'hostID', and
       // the optional 'systemID'.
  
       // Other connection types, like 'local' (used for testing
       // purposes skipping any interaction with the bank service)
       // and 'fints' are all work in progress!

     }


  .. ts:def:: BankConnectionBackup
     
     interface BankConnectionBackup {

       // The information needed in this type depend entirely
       // on which connectionis being restored.

     }

  **Response:**

  :status 409 Conflict: The ``name`` field exists already for
    the requesting user.


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

   List available bank connections.


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

   Get information about one bank connection.

   .. ts:def:: BankConnectionInfo
      
      interface BankConnectionInfo {
         name: string;

         connectionType: string;

         ready: boolean;

         // Did the user review the bank's keys?
         bankKeysReviewed: boolean;
      }


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

   Initialize the connection by talking to the bank.

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

   Make a passphrase-encrypted backup of this connection.

..
  not implemented.

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

   Update accounts that are accessible via this bank connection.

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

   List the bank accounts that are downloaded into this bank connection
   but aren't imported yet:

  .. ts:def:: BankAccount

     interface BankAccount {
       
       // iban
       iban: string;

       // bic
       bic: string;

       // account holder
       holder: string;

       // account label as given by the bank
       account: string;
     }

.. http:post:: {nexusBase}/bank-connections/{connid}/accounts/import

   Import one bank account, allowing the user to name it.

  .. ts:def:: ImportBankAccount

     interface ImportBankAccount {

       // alphanumeric identifier given by the bank to
       // the bank account to import.
       accountId: string;

       // alphanumeric name chosen by the user to identify
       // locally such imported bank account.
       localName: string;
     }

Facades
-------

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

  List available facades.  

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

  Create a new facade; it requires a `FacadeInfo` as the request's body.

.. http:get:: {nexus}/facades/${fcid}

  Get details about a facade.

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

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

        // Name of the user that created the facade.
        // Whenever the facade accesses a resource it is allowed to
        // access, the creator must *also* have access to that resource.
        creator: 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.
        config: any;
     }


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

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

   List supported bank connection protocols.

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

   Check if the 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 the nexus database.  It will just make a request to the bank
  and return the answer.

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

  .. warning::

    Use with care.  Typically only necessary for testing and debugging.
  
  Perform an EBICS upload transaction of type ``msg``.
  This request will not affect any bank account or other state
  in the nexus database.  It will just make a request to the bank
  and return the answer.


The taler-wire-gateway facade
-----------------------------

The ``taler-wire-gateway`` facade has the following configuration:


.. ts:def:: TalerWireGatewayFacadeConfig
   
   interface TalerWireGatewayFacadeConfig {
     // Bank account and connection that is
     // abstracted over.
     bankAccount: string;
     bankConnection: string;

     // Corresponds to whether we trust C52, C53 or C54 (SEPA ICT)
     // for incoming transfers.
     reserveTransferLevel: "statement" | "report" | "notification";

     // Time between incremental requests
     intervalIncremental: string;

     // FIXME:  maybe more scheduling parameters?
   }