commit 56b11e2ee4a5cad960701b854e86de70e6291600
parent 227aa1bb0fc61cc3f79600737d11a30ea0f58431
Author: Christian Grothoff <christian@grothoff.org>
Date: Sat, 27 Dec 2025 15:26:38 +0100
new man pages
Diffstat:
5 files changed, 179 insertions(+), 12 deletions(-)
diff --git a/conf.py b/conf.py
@@ -661,6 +661,20 @@ man_pages = [
1,
),
(
+ "manpages/taler-merchant-report-generator.1",
+ "taler-merchant-report-generator",
+ "background job that periodically fetches and submits reports",
+ "GNU Taler contributors",
+ 1,
+ ),
+ (
+ "manpages/taler-merchant-report-generator-email.1",
+ "taler-merchant-report-generator-email",
+ "helper for taler-merchant-report-generator that handles submission via e-mail",
+ "GNU Taler contributors",
+ 1,
+ ),
+ (
"manpages/taler-merchant-kyccheck.1",
"taler-merchant-kyccheck",
"ask exchange about KYC status of merchant bank accounts",
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
@@ -3579,7 +3579,7 @@ Adding groups
.. http:post:: [/instances/$INSTANCES]/private/groups
- This is used to create a report.
+ This is used to create a group.
**Required permission:** ``groups-write``
@@ -5905,9 +5905,9 @@ Removing reports
Pots
----
-Pots are a backend feature that is used to send periodic
-reports to the merchant. Reports are sent using notification
-helper programs which must be configured for each merchant backend.
+Pots are a backend feature that is used for accounting. Transacted
+amounts can be assigned into pots, for example to separate out
+tips and taxes from revenue for reporting.
Since protocol **vPOTS**.
@@ -5945,7 +5945,7 @@ Adding pots
// Name of the pot. Must be unique per instance.
pot_name: string;
- // Currency of the pod. Must be a valid Taler currency string.
+ // Currency of the pot. Must be a valid Taler currency string.
currency: string;
}
@@ -5981,7 +5981,7 @@ Editing pots
The pot or instance is unknown to the backend.
:http:statuscode:`409 Conflict`:
The pot total did not match the expected total
- and thus resetting the pod failed.
+ and thus resetting the pot failed.
**Details:**
@@ -5999,12 +5999,15 @@ Editing pots
// Expected current total amount in the pot.
// Should be given if ``new_pot_total`` is specified
// as this allows checking that the pot total did
- // not change in the meantime.
+ // not change in the meantime. However, this is
+ // not enforced server-side, the client may choose
+ // to not use this safety-measure.
expected_pot_total?: Amount;
- // Expected new total amount to store in the pod.
+ // Expected new total amount to store in the pot.
// Does **not** have to be in the same currency as
- // the existing amount in the pot.
+ // the existing amount in the pot. Used to reset
+ // the pot and/or change the currency.
new_pot_total?: Amount;
}
@@ -6060,7 +6063,7 @@ Inspecting pots
// Name of the pot. Must be unique per instance.
pot_name: string;
- // Current total amount in the pod.
+ // Current total amount in the pot.
pot_total: Amount;
}
@@ -6093,7 +6096,7 @@ Inspecting pots
// Name of the pot. Must be unique per instance.
pot_name: string;
- // Current total amount in the pod.
+ // Current total amount in the pot.
pot_total: Amount;
}
diff --git a/manpages/taler-merchant-report-generator-email.1.rst b/manpages/taler-merchant-report-generator-email.1.rst
@@ -0,0 +1,53 @@
+taler-merchant-report-generator-email(1)
+########################################
+
+.. only:: html
+
+ Name
+ ====
+
+ **taler-merchant-report-generator-email** - transmit periodic reports via email
+
+
+Synopsis
+========
+
+**taler-merchant-report-generator-email**
+[**-d** *SUBJECT*]
+[**-h**]
+[**-m** *MIMETYPE*]
+[**-t** *ADDRESS*]
+
+Description
+===========
+
+**taler-merchant-report-generator-email** is a script that
+transmits reports via e-mail. It is used by the
+taler-merchant-report-generator. The main content of the e-mail
+must be passed from standard input.
+
+Its options are as follows:
+
+**-d** *SUBJECT*
+ Use *SUBJECT* as the e-mail subject.
+
+**-h** \| **--help**
+ Print short help on options.
+
+**-m** *MIMETYPE*
+ The MIMETYPE to use to encode the data from standard input.
+ "text/plain" is treated specially in that no attachment is used.
+
+**-t** *ADDRESS*
+ Specifies the target e-mail address for the report.
+
+See Also
+========
+
+taler-merchant.conf(5), taler-merchant-report-generator(1).
+
+Bugs
+====
+
+Report bugs by using https://bugs.taler.net or by sending electronic
+mail to <taler@gnu.org>.
diff --git a/manpages/taler-merchant-report-generator.1.rst b/manpages/taler-merchant-report-generator.1.rst
@@ -0,0 +1,69 @@
+taler-merchant-report-generator(1)
+##################################
+
+.. only:: html
+
+ Name
+ ====
+
+ **taler-merchant-report-generator** - fetch and transmit periodic reports
+
+
+Synopsis
+========
+
+**taler-merchant-report-generator**
+[**-c** *FILENAME* | **--config=**\ \ *FILENAME*]
+[**-h** | **--help**]
+[**-L** *LOGLEVEL* | **--loglevel=**\ \ *LOGLEVEL*]
+[**-l** *FILENAME* | **--logfile=**\ \ *FILENAME*]
+[**-T** *USEC* | **--timetravel**\ \ *USEC*]
+[**-t** | **--test**]
+[**-v** | **--version**]
+
+Description
+===========
+
+**taler-merchant-report-generator** is a background job that
+peridoically fetches reports from the merchant backend and
+transmits them using report-generator helper processes. This
+is typically used to send statistical data for accounting.
+
+Its options are as follows:
+
+**-c** *FILENAME* \| **--config=**\ \ *FILENAME*
+ Use the configuration and other resources for the merchant to operate
+ from *FILENAME*.
+
+**-h** \| **--help**
+ Print short help on options.
+
+**-L** *LOGLEVEL* \| **--loglevel=**\ \ *LOGLEVEL*
+ Specifies the log level to use. Accepted values are: ``DEBUG``, ``INFO``,
+ ``WARNING``, ``ERROR``.
+
+**-l** *FILENAME* \| **--logfile=**\ \ *FILENAME*
+ Send logging output to *FILENAME*.
+
+**-T** *USEC* \| **--timetravel=**\ \ *USEC*
+ Modify the system time by *USEC* microseconds.
+ *USEC* may be prefixed with ``+`` or ``-`` (e.g. ``-T +300``).
+ This option is intended for debugging/testing only.
+
+**-t** \| **--test**
+ Run in test mode. Only runs until the current list of bank
+ transactions have all been checked.
+
+**-v** \| **–version**
+ Print version information.
+
+See Also
+========
+
+taler-merchant.conf(5).
+
+Bugs
+====
+
+Report bugs by using https://bugs.taler.net or by sending electronic
+mail to <taler@gnu.org>.
diff --git a/manpages/taler-merchant.conf.5.rst b/manpages/taler-merchant.conf.5.rst
@@ -214,7 +214,7 @@ PRIVACY_DIR
PRIVACY_ETAG
Works the same as ``TERMS_ETAG``, just for the privacy policy.
-
+
DEFAULT_PERSONA
Which "Persona" should be chosen by default for new clients
using the SPA? The setting can always changed locally in the
@@ -292,6 +292,34 @@ DISABLED
Set to YES to disable this exchange. Optional option, defaults to NO.
+REPORT GENERATION
+-----------------
+
+The merchant backend can be used to fetch and submit periodic reports.
+The submission is handled using report generators. These are binaries
+that receive the main report from standard input (stdin), and are told:
+
+ * the mime type using a "-m" command-line option,
+ * the report target address using a "-t" command-line option, and
+ * a report description using a "-d" command-line option.
+
+The report generators should return 0 on success. Custom report generators are
+configured using configuration sections [report-generator-$NAME], where $NAME
+is a merchant-given name for the report generator. The following options must
+be given in each “[report-generator-$NAME]” section.
+
+BINARY
+ Name of the binary to execute. Currently this must be a single
+ filename (usually with the path), no command-line arguments may
+ be specified.
+
+Default report generators include:
+
+* ``[report-generator-email]`` with the BINARY
+ taler-merchant-report-generator-email will
+ send reports via e-mail using the UNIX mail program.
+
+
SEE ALSO
========
