nexus fetch: cli man & manual

3 files changed, 59 insertions, 38 deletions

diff --git a/libeufin/nexus-manual.rst b/libeufin/nexus-manual.rst
index a434e1dc..447637d3 100644
--- a/libeufin/nexus-manual.rst
+++ b/libeufin/nexus-manual.rst
@@ -108,10 +108,10 @@ Sending payments
 
 Sending payments must follow a successful `EBICS subscriber setup <ebics-setup>`_,
 where the bank obtained the subscriber keys, and the subscriber accepted the
-bank keys.  The responsible subcommand is ``ebics-submit``, and its
-configuration is a **superset** of core-config_.  On top of that, it
-expects the database connection string, and *optionally* a frequency to
-check for submittable payments in the database.
+bank keys.  The responsible subcommand for sending payments is ``ebics-submit``,
+and its configuration is a **superset** of core-config_.  On top of that, it
+expects the database connection string, and *optionally* a frequency to check
+for submittable payments in the database.
 
 The connection string is specified as
 
@@ -145,7 +145,7 @@ For testing
 -----------
 
 The ``ebics-submit`` subcommand is **not** suitable to send arbitrary
-payments, but rather to *submit* initiated payments that may be found
+payments, but rather to submit initiated payments that may be found
 in the database.
 
 Such initiated payments may be refunds of incoming payments with a subject
@@ -183,18 +183,7 @@ the database, submit what is submittable, and return.
 For production
 --------------
 
-The ``ebics-submit`` subcommand can run in long-polling, fixed frequency, or
-transient mode.
-
-The long-polling mode causes the command to never return and to submit the payments
-to the bank *as soon as they arrive in the database*.  To activate this mode, set
-the frequency to ``0s`` in the configuration.  Assuming that ``$config_long_polling``
-is set as described above, the following invocation would make ``ebics-submit`` run
-in long-polling mode:
-
-.. code-block:: console
-
-  libeufin-nexus ebics-submit -c $config_file
+The ``ebics-submit`` subcommand can run in fixed frequency, or transient mode.
 
 The fixed frequency mode causes the command to check the database every time the
 frequency period expires.  To activate this mode, and -- for example -- set a frequency
@@ -203,21 +192,55 @@ of five minutes, set the configuration value ``FREQUENCY`` to ``5m``.  Assuming
 make ``ebics-submit`` check the database every five minutes, and submit any initiated
 payment according to their submission state.
 
-.. note::
-
-  long-polling is still unsupported and resubmission of payments with a
-  ``transient_failure`` after a long-polled trigger is under discussion.
-
 .. code-block:: console
 
   libeufin-nexus ebics-submit -c $config_fixed_frequency
 
 
-Finally, transient mode causes ``ebics-submit`` to check the database only once,
-submit any initiated payment according to their submission state, and soon return.
+Transient mode causes ``ebics-submit`` to check the database only once, submit any
+initiated payment according to their submission state, and return.
 
 .. code-block:: console
 
   libeufin-nexus ebics-submit -c $config
 
-There's no need to set the frequency in the configuration.
+Downloading records
+===================
+
+Downloading records must follow a successful `EBICS subscriber setup <ebics-setup>`_,
+where the bank obtained the subscriber keys, and the subscriber accepted the bank keys.
+
+The following configuration sets the (mandatory) database connection and a log directory
+where any downloaded record would be stored.
+
+.. code-block:: console
+  
+  [nexus-postgres]
+  config = postgres:///nexus
+  [nexus-fetch]
+  statement_log_directory = $LIBEUFIN_DATA_HOME/camt
+
+Assuming that ``$config_file`` contains any required option, the following command
+would download any unseen notifications (as camt.054 files).
+
+.. code-block:: console
+
+  libeufin-nexus ebics-fetch -c $config_file --transient
+
+The ``--transient`` flag makes the command to download only once and return.  If the
+bank returned any records, look in ``$LIBEUFIN_DATA_HOME/cat/YYYY-MM-DD`` to find them.
+YYYY-MM-DD is the date when the download took place.
+
+To activate periodic downloads, add the following setting to the ``nexus-fetch``
+configuration section in ``$config_file``:
+
+.. code-block:: console
+
+   frequency = 5m
+
+The following invocation would then download records every five minutes, asking the bank
+to only return documents that are timestamped *from* (inclusive) the last incoming transaction.
+
+.. code-block:: console
+
+  libeufin-nexus ebics-fetch -c $config_file
diff --git a/manpages/libeufin-nexus.1.rst b/manpages/libeufin-nexus.1.rst
index f4df6558..aee26e65 100644
--- a/manpages/libeufin-nexus.1.rst
+++ b/manpages/libeufin-nexus.1.rst
@@ -89,8 +89,7 @@ Its options are as follows:
 **-c** \| **--config** \ ‌\ *FILENAME*
    Specifies the configuration file.
 **--transient**
-   This flag, enabled by default, causes the command to run only once without any long-polling behaviour.
-   The configuration value FREQUENCY gets therefore ignored.
+   This flag, enabled by default, causes the command to check the database and submit only once, and then return.
 
 ebics-fetch
 -----------
@@ -102,10 +101,15 @@ This subcommands download banking records via EBICS.  By default it downloads no
 **-c** \| **--config** \ ‌\ *FILENAME*
    Specifies the configuration file.
 **--transient**
-   This flag, enabled by default, causes the command to run only once without any long-polling behaviour.
-   The configuration value FREQUENCY gets therefore ignored.
+   This flag, enabled by default, causes the command to perform one download and return.
 **--only-statements**
    It downloads statements (instead of notifications) in the form of camt.053 documents.
+**--only-ack**
+   It downloads payment submissions acknowledgements (instead of notifications) in the form of pain.002 documents.
+**--only-reports**
+   It downloads only intraday reports (instead of notifications) in the form of camt.052 documents.
+**--pinned-start**
+  Only supported in --transient mode, this option lets specify the earliest timestamp of the downloaded documents.  The latest timestamp is always the current time.
 
 
 SEE ALSO
diff --git a/manpages/libeufin-nexus.conf.5.rst b/manpages/libeufin-nexus.conf.5.rst
index e5a712a8..14161918 100644
--- a/manpages/libeufin-nexus.conf.5.rst
+++ b/manpages/libeufin-nexus.conf.5.rst
@@ -101,12 +101,8 @@ FREQUENCY
   Duration value to instruct the ``ebics-submit`` subcommand how much to wait
   before checking the database again to find new unsubmitted payments.  The duration
   must be expressed with a number followed by the time unit.  The following time
-  units are supported: 's' (seconds), 'm' (minutes), 'h' (hours).
-  For example, the value *5m* causes retries to be run every five minutes.  Whenever
-  the given number is zero, the retries are long-polled.  Note: the current version
-  does NOT support long-polling but would instead run in transient mode, whenever
-  the duration number is zero.  Finally, even with a duration number of zero, the
-  duration unit must be specified.
+  units are supported: 's' (seconds), 'm' (minutes), 'h' (hours).  For example,
+  the value *5m* causes retries to be run every five minutes.
 
 SUBMISSIONS_LOG_DIRECTORY
   Optional value to define the path where the pain.001 documents would be stored
@@ -128,9 +124,7 @@ FREQUENCY
   download from the bank.  The duration must be expressed with a number followed
   by the time unit.  The following time units are supported: 's' (seconds), 'm'
   (minutes), 'h' (hours).  For example, the value *5m* causes downloads to be run
-  every five minutes.  Whenever the given number is zero, the retries are long-polled.
-  Note: the current version does NOT support long-polling but would instead run in
-  transient mode.  Note: long polling depends also by the bank offering it.
+  every five minutes.
 
 STATEMENT_LOG_DIRECTORY
   Optional value to define the path where the downloaded documents would be stored