Passing over Nexus API, ~55%.

Moved a recurrent definition to the api-common
document and elaborated over the FetchParams value
in case of "submit" tasks.

2 files changed, 75 insertions, 43 deletions

diff --git a/libeufin/api-common.rst b/libeufin/api-common.rst
index 83da130f..7ec1f09c 100644
--- a/libeufin/api-common.rst
+++ b/libeufin/api-common.rst
@@ -38,3 +38,41 @@ Amounts
 Amounts have the ``$currency:X.Y`` format, where the
 fractional part is optional and may contain at most two
 digits.
+
+Fetch params
+^^^^^^^^^^^^
+
+.. _fetch-params:
+
+.. ts:def:: FetchParams
+
+  interface FetchParams {
+
+    // Because transactions are delivered by banks in "batches",
+    // then every batch can have different qualities.  This value
+    // lets the request specify which type of batch ought to be
+    // returned.  Currently, the following two type are supported:
+    //
+    // 'report': typically includes only non booked transactions.
+    // 'statement': typically includes only booked transactions.
+    level: "report" | "statement" | "all";
+
+    // This type indicates the time range of the query.
+    // It allows the following values:
+    //
+    // 'latest': retrieves the last transactions from the bank.
+    //           If there are older unread transactions, those will *not*
+    //           be downloaded.
+    //
+    // 'all': retrieves all the transactions from the bank,
+    //        until the oldest.
+    //
+    // 'previous-days': currently *not* implemented, it will allow
+    //                  the request to download transactions from
+    //                  today until N days before.
+    //
+    // 'since-last': retrieves all the transactions since the last
+    //               time one was downloaded.
+    //
+    rangeType: "latest" | "all" | "previous-days" | "since-last";
+  };
diff --git a/libeufin/api-nexus.rst b/libeufin/api-nexus.rst
index 0e08d1d1..e2cb1f1f 100644
--- a/libeufin/api-nexus.rst
+++ b/libeufin/api-nexus.rst
@@ -148,6 +148,9 @@ 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.
@@ -357,38 +360,14 @@ tracks the initiations of payments.
 
   **Request:**
 
+  Refer to :ref:`FetchParams <fetch-params>` for
+  ``level`` and ``rangeType`` specifications.
+
   .. ts:def:: CollectedTransaction
 
      interface CollectedTransaction {
-
-         // This type indicates the time range of the query.
-         // It allows the following values:
-         //
-         // 'latest': retrieves the last transactions from the bank.
-         //           If there are older unread transactions, those will *not*
-         //           be downloaded.
-         //
-         // 'all': retrieves all the transactions from the bank,
-         //        until the oldest.
-         //
-         // 'previous-days': currently *not* implemented, it will allow
-         //                  the request to download transactions from
-         //                  today until N days before.
-         //
-         // 'since-last': retrieves all the transactions since the last
-         //               time one was downloaded.
-         //
-         rangeType: string;
-
-         // Because transactions are delivered by banks in "batches",
-         // then every batch can have different qualities.  This value
-         // lets the request specify which type of batch ought to be
-         // returned.  Currently, the following two type are supported:
-         //
-         // 'report': typically includes only non booked transactions.
-         // 'statement': typically includes only booked transactions.
          level: string;
-
+         rangeType: string;
          // Bank connection to use.  Uses the default bank connection,
          // when not given.
          bankConnection: string?;
@@ -501,6 +480,7 @@ Scheduling API
   .. ts:def:: ScheduleTask
 
     interface ScheduleTask {
+      // Name to assign to the task being created.
       name: string;
 
       // a Unix-compatible cron pattern representing
@@ -513,17 +493,21 @@ Scheduling API
       // bank account).
       type: string;
 
-      // Currently only used for "fetch" operations
-      params: {
-        level: "report" | "statement" | "all";
-        rangeType: "latest" | "all" | "previous-days" | "since-last";
-      };
+      // 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
@@ -533,14 +517,26 @@ Scheduling API
      // the scheduling feature.
 
      interface NexusTask {
-       // FIXME: document all.
+       // 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;
-       taskParams: 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;
      }
 
@@ -551,9 +547,11 @@ Scheduling API
 
 .. http:get:: {nexusBase}/bank-accounts/{acctid}/schedule
 
+   Shows all the scheduled tasks from ``acctid``.
+
   **Response**
 
-  .. code-block:: ts
+  .. ts:def:: TaskCollection
 
     interface TaskCollection {
 
@@ -562,12 +560,8 @@ Scheduling API
 
         'task-name': {
           cronspec: string;
-          type: string; // fetch | submit
-
-          // Depends on the type.  Submit has it empty, whereas
-          // the fetch type includes the time range and the report
-          // level.
-          params: any;
+          type: "fetch" | "submit";
+          params: FetchParams;
         }
       }
     }