docs (wallet, nfc)

6 files changed, 120 insertions, 15 deletions

diff --git a/index.rst b/index.rst
index 060795f..8548e52 100644
--- a/index.rst
+++ b/index.rst
@@ -53,6 +53,7 @@ Documentation Overview
   core/index
   taler-exchange-manual
   taler-merchant-manual
+  taler-wallet
   taler-nfc-guide.rst
   taler-merchant-api-tutorial
   taler-bank-manual
diff --git a/taler-bank-manual.rst b/taler-bank-manual.rst
index c85e0aa..4c1b573 100644
--- a/taler-bank-manual.rst
+++ b/taler-bank-manual.rst
@@ -1,5 +1,5 @@
-The GNU Taler bank manual
-#########################
+GNU Taler bank manual
+#####################
 
 Introduction
 ============
diff --git a/taler-merchant-api-tutorial.rst b/taler-merchant-api-tutorial.rst
index 2981e43..bfae7f0 100644
--- a/taler-merchant-api-tutorial.rst
+++ b/taler-merchant-api-tutorial.rst
@@ -1,4 +1,4 @@
-The GNU Taler Merchant API Tutorial
+GNU Taler Merchant API Tutorial
 ###################################
 
 Introduction
@@ -27,8 +27,6 @@ This version of the tutorial has examples for Python3. It uses the
 requests library for HTTP requests. Versions for other
 languages/environments are available as well.
 
-examples
-git
 If you want to look at some simple, running examples, check out these:
 
 -  The `essay
@@ -346,7 +344,6 @@ Advanced topics
 Detecting the Presence of the Taler Wallet
 ------------------------------------------
 
-wallet
 Taler offers ways to detect whether a user has the wallet installed in
 their browser. This allows Web sites to adapt accordingly. Note that not
 all platforms can do presence detection reliably. Some platforms might
@@ -504,9 +501,6 @@ previous payment.
 The Taler Order Format
 ----------------------
 
-contract
-terms
-order
 A Taler order can specify many details about the payment. This section
 describes each of the fields in depth.
 
diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst
index d668de3..1dfbfc7 100644
--- a/taler-merchant-manual.rst
+++ b/taler-merchant-manual.rst
@@ -1,5 +1,5 @@
 GNU Taler Merchant Backend Operator Manual
-##############################################
+##########################################
 
 Introduction
 ============
diff --git a/taler-nfc-guide.rst b/taler-nfc-guide.rst
index f964674..029b84f 100644
--- a/taler-nfc-guide.rst
+++ b/taler-nfc-guide.rst
@@ -23,10 +23,28 @@ The following steps show a simple payment process with GNU Taler.  Examples are
 written in `Bash <https://www.gnu.org/software/bash/>`_ syntax,
 using `curl <https://curl.haxx.se/docs/manpage.html>`_ to make HTTP(S) requests.
 
+
 1. The merchant creates an *order*, which contains the details of the payment
    and the product/service that the customer will receive.
    An order is identified by an alphanumeric *order ID*.
 
+   The *fulfillment URL* is an URL that the wallet will redirect the customer
+   to once the payment is complete.  For digital products, this is typically an
+   ``https(s)://`` URL that renders the purchased content.  For physical
+   products and in-store purchases, a ``taler://fulfillment-success/<message>``
+   URL should be specified instead.  The wallet will display the URL-encoded
+   UTF-8 text ``<message>`` when the payment has succeeded.
+
+   .. hint::
+
+     When an ``http(s)://`` URL is used as the fulfillment URL in an in-store / NFC payment,
+     the user might not be able to view the page, as request tunneling only works for requests
+     made by the wallet to the merchant backend / exchange.
+
+     In these situations, wallets should display to the user that a page to view the purchase
+     can be opened, and give a warning if it is detected that the devices does not have Internet
+     connectivity.
+
    The following :http:post:`/order` request to the merchant backend creates a
    simple order:
 
@@ -77,7 +95,7 @@ using `curl <https://curl.haxx.se/docs/manpage.html>`_ to make HTTP(S) requests.
    The details of ``taler://`` URIs are specified :ref:`here <taler-uri-scheme>`.
 
 3. The wallet processes the ``taler://pay/`` URI.  In this example, we use the
-   command line wallet:
+   command-line wallet:
 
    .. code-block:: sh
 
@@ -90,6 +108,12 @@ using `curl <https://curl.haxx.se/docs/manpage.html>`_ to make HTTP(S) requests.
      $ taler-wallet-cli pay-uri 'taler://pay/backend.demo.taler.net/-/-/2019.255-02YDHMXCBQP6J'
      # [... User is asked to confirm the payment ...]
 
+   .. hint::
+
+     The command-line wallet is typically used by developers and not by end-users.
+     See the :ref:`wallet manual <command-line-wallet>` for installation instructions.
+
+
 4. The merchant checks the payment status again:
 
    .. code-block:: sh
@@ -104,6 +128,16 @@ using `curl <https://curl.haxx.se/docs/manpage.html>`_ to make HTTP(S) requests.
        # ... (some fields omitted)
      }
 
+   .. note::
+
+     When paying for digital products displayed on a Web site identified by the
+     fulfillment URL, the merchant only needs to check the payment status
+     before responding with the fulfillment page.
+
+     For in-store payments, the merchant must periodically check the payment status.
+     Instead of polling in a busy loop, the ``long_poll_ms`` parameter of :http:get:`/check-payment`
+     should be used.
+
 
 Taler NFC Basics
 ================
@@ -126,7 +160,8 @@ During the time that the wallet is paired with a reader, there is state
 associated with the communication channel. Most importantly, the first message
 sent by the reader to the wallet must be a ``SELECT FILE (=0xA4)`` that selects
 the GNU Taler AID.  Messages that are sent before the correct ``SELECT FILE``
-message result in undefined behavior.
+message results in implementation-defined behavior, such as the tag disconnecting,
+ignoring the message or an app other than the wallet receiving the message.
 
 The reader sends commands to the wallet with the ``PUT DATA (=0xDA)``
 instruction, using the instruction parameters ``0x0100``, denoting a
@@ -159,10 +194,11 @@ first byte.  The rest of the
 body is interpreted depending on the TID.
 
 .. list-table::
-  :widths: 5 50
+  :widths: 15 50
   :header-rows: 1
 
-  * - TID (wallet to reader)
+  * - TID
+      (wallet to reader)
     - Description
   * - ``0x03``
     - Accept the UTF-8 encoded JSON object in the remainder of the command data as a request tunneling request.
@@ -228,7 +264,7 @@ The request tunneling request/response JSON messages have the following schema:
     // Request headers
     headers?: { [name: string]: string };
 
-    // JSON body for the request, only applicable to GET requests
+    // JSON body for the request, only applicable to POST requests
     body?: object;
   }
 
diff --git a/taler-wallet.rst b/taler-wallet.rst
new file mode 100644
index 0000000..50bf0ef
--- /dev/null
+++ b/taler-wallet.rst
@@ -0,0 +1,74 @@
+GNU Taler Wallet Manual
+#######################
+
+The GNU Taler wallet allows customers to withdraw and spend digital cash.
+
+.. _command-line-wallet:
+
+Command-line Wallet
+===================
+
+The command-line wallet is used primarily for testing by developers.
+
+Building from source
+--------------------
+
+.. code-block:: sh
+
+  $ git clone https://git.taler.net/wallet-core.git
+  $ cd wallet-core
+  $ ./configure --prefix=$INSTALL_PREFIX
+  $ make && make install
+
+The wallet command-line interface should then be available as ``taler-wallet-cli`` under ``$INSTALL_PREFIX/bin``.
+
+Installation via NPM
+--------------------
+
+The wallet can also obtained via NPM, the Node Package Manager.
+
+To install the wallet as a global package, run:
+
+.. code-block:: sh
+
+  $ npm install -g taler-wallet
+  # check if installation was successful
+  $ taler-wallet-cli --version
+
+To install the wallet only for your user, run:
+
+.. code-block:: sh
+
+  $ npm install -g --prefix=$HOME/local taler-wallet
+  # check if installation was successful
+  $ taler-wallet-cli --version
+  # If this fails, make sure that $HOME/local/bin is in your $PATH
+
+To use the wallet as a library in your own project, run:
+
+.. code-block:: sh
+
+  $ npm install taler-wallet
+
+
+WebExtension Wallet
+===================
+
+Building from source
+--------------------
+
+.. code-block:: sh
+
+  $ git clone https://git.taler.net/wallet-core.git
+  $ cd wallet-core
+  $ ./configure
+  $ make webex-stable
+  # Packaged extension now available as:
+  # dist/taler-wallet-$VERSION.zip
+
+
+Android Wallet
+==============
+
+*TODO*
+