From 5a629189695315601ad61c7bff98277fca7674c5 Mon Sep 17 00:00:00 2001
From: MS <ms@taler.net>
Date: Mon, 16 Aug 2021 03:06:37 -1100
Subject: drafting Anastasis facade/API

---
 libeufin/api-nexus.rst | 111 ++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 110 insertions(+), 1 deletion(-)

diff --git a/libeufin/api-nexus.rst b/libeufin/api-nexus.rst
index 1c51372a..5aac6d45 100644
--- a/libeufin/api-nexus.rst
+++ b/libeufin/api-nexus.rst
@@ -822,7 +822,7 @@ Facades
         name: string;
 
         // Type of the facade.
-        // For example, "taler-wire-gateway".
+        // For example, "taler-wire-gateway" or "anastasis".
         type: string;
 
         // Bank accounts that the facade has read/write
@@ -890,6 +890,115 @@ They are namespaced under the ``/ebics/`` sub-resource.
   in the 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.  It is named after the typical user -
+a Anastasis service - but can be used in any case where only the
+incoming transactions are of interest.
+
+.. http:get:: ${BASE_URL}/history/incoming
+
+  Return a list of transactions made to the customer.
+
+  The bank account of the customer is determined via the base URL and/or the
+  user name in the ``Authorization`` header.  In fact the transaction history
+  might come from a "virtual" account, where multiple real bank accounts are
+  merged into one history.
+
+  Transactions are identified by an opaque numeric identifier, referred to here
+  as *row ID*.  The semantics of the row ID (including its sorting order) are
+  determined by the bank server and completely opaque to the client.
+
+  The list of returned transactions is determined by a row ID *starting point*
+  and a signed non-zero integer *delta*:
+
+  * If *delta* is positive, return 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, the bank 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
+    the bank 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. The bank 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. The bank 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.
+      // This must be one of the 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;
+
+    }
+
+The anastasis facade
+--------------------
+
+The ``anastasis`` facade has the following configuration:
+
+
+.. ts:def:: AnastasisFacadeConfig
+
+   interface AnastasisFacadeConfig {
+     // Bank account and connection that is abstracted over.
+     bankAccount: string;
+     bankConnection: string;
+
+     currency: string;
+
+     // Corresponds to whether we trust C52, C53 or C54 (SEPA ICT)
+     // for incoming transfers.
+     reserveTransferLevel: "statement" | "report" | "notification";
+   }
 
 The taler-wire-gateway facade
 -----------------------------
-- 
cgit v1.2.3