[taler-docs] branch master updated: move choice interfaces to order

[gnunet]

This is an automated email from the git hooks/post-receive script.

christian-blaettler pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 68e70426 move choice interfaces to order
68e70426 is described below

commit 68e704265d4cff33f3cf6cf66eb94a1bb4279ef7
Author: Christian Blättler <blatc2@bfh.ch>
AuthorDate: Fri Mar 29 09:33:02 2024 +0100

    move choice interfaces to order
---
 core/api-merchant.rst | 179 +++++++++++++++++++++++++-------------------------
 1 file changed, 90 insertions(+), 89 deletions(-)

diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index 1dc128bf..3d20d838 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -2051,6 +2051,7 @@ Creating orders
       // False can make sense if the ORDER_ID is sufficiently
       // high entropy to prevent adversarial claims (like it is
       // if the backend auto-generates one). Default is 'true'.
+      // Note: This is NOT related to tokens used for subscriptins or refunds.
       create_token?: boolean;
 
       // OTP device ID to associate with the order.
@@ -2090,15 +2091,15 @@ Creating orders
       // in case order IDs are guessable).
       public_reorder_url?: string;
 
-      // See documentation of ``fulfillment_url`` field in ``ContractTerms``.
+      // See documentation of ``fulfillment_url`` field in `ContractTerms`.
       // Either fulfillment_url or fulfillment_message must be specified.
       // When creating an order, the fulfillment URL can
       // contain ``${ORDER_ID}`` which will be substituted with the
       // order ID of the newly created order.
       fulfillment_url?: string;
 
-      // See documentation of fulfillment_message in `ContractTerms`.
-      // Either fulfillment_url or fulfillment_message must be specified.
+      // See documentation of ``fulfillment_message`` in `ContractTerms`.
+      // Either ``fulfillment_url`` or ``fulfillment_message`` must be 
specified.
       fulfillment_message?: string;
 
       // Map from IETF BCP 47 language tags to localized fulfillment
@@ -2158,6 +2159,89 @@ Creating orders
 
     }
 
+
+The `OrderChoice` object describes a possible choice within an order. The
+choice is done by the wallet and consists of in- and outputs. In the example
+of buying an article, the merchant could present the customer with the choice
+to use a valid subscription token or pay using a gift voucher. Available since
+protocol **vSUBSCRIBE**.
+
+.. ts:def:: OrderChoice
+
+  interface OrderChoice {
+    // Inputs that must be provided by the customer, if this choice is 
selected.
+    inputs: OrderInput[];
+
+    // Outputs provided by the merchant, if this choice is selected.
+    outputs: ContractOutput[];
+  }
+
+.. ts:def:: OrderInput
+
+  // For now, only token inputs are supported.
+  type OrderInput = OrderInputToken;
+
+.. ts:def:: OrderInputToken
+
+  interface OrderInputToken {
+
+    // Token input.
+    type: "token";
+
+    // Token family slug as configured in the merchant backend. Slug is unique
+    // across all configured tokens of a merchant.
+    token_family_slug: string;
+
+    // Start of the validity period of the token. Based on this, the merchant
+    // will select the relevant signing key.
+    valid_after: Timestamp;
+
+    // How many units of the input are required.
+    // Defaults to 1 if not specified. Output with count == 0 are ignored by
+    // the merchant backend.
+    count?: Integer;
+
+  }
+
+.. ts:def:: OrderOutput
+
+  type OrderOutput = OrderOutputToken | OrderOutputTaxReceipt;
+
+.. ts:def:: OrderOutputToken
+
+  interface OrderOutputToken {
+
+    // Token output.
+    type: "token";
+
+    // Token family slug as configured in the merchant backend. Slug is unique
+    // across all configured tokens of a merchant.
+    token_family_slug: string;
+
+    // Start of the validity period of the token. Based on this, the merchant
+    // will select the relevant signing key.
+    valid_after: Timestamp;
+
+    // How many units of the output are issued by the merchant.
+    // Defaults to 1 if not specified. Output with count == 0 are ignored by
+    // the merchant backend.
+    count?: Integer;
+
+  }
+
+.. ts:def:: OrderOutputTaxReceipt
+
+  interface OrderOutputTaxReceipt {
+
+    // Tax receipt output.
+    type: "tax-receipt";
+
+    // Base URL of the donation authority that will
+    // issue the tax receipt.
+    donau_url: string;
+
+  }
+
   The following `MinimalInventoryProduct` can be provided if the parts of the
   order are inventory-based, that is if the `PostOrderRequest` uses
   ``inventory_products``. For such products, which must be in the backend's 
inventory,
@@ -2172,9 +2256,9 @@ Creating orders
 
   .. ts:def:: MinimalInventoryProduct
 
-    Note that if the frontend does give details beyond these,
-    it will override those details (including price or taxes)
-    that the backend would otherwise fill in via the inventory.
+    // Note that if the frontend does give details beyond these,
+    // it will override those details (including price or taxes)
+    // that the backend would otherwise fill in via the inventory.
 
     interface MinimalInventoryProduct {
       // Which product is requested (here mandatory!).
@@ -3924,89 +4008,6 @@ The wallet must select an exchange that either the 
merchant accepts directly by
 listing it in the exchanges array, or for which the merchant accepts an auditor
 that audits that exchange by listing it in the auditors array.
 
-The `ContractChoice` object describes a possible choice within a contract. The
-choice is done by the customer and consists of in- and outputs. In the example
-of buying an article, the merchant could present the customer with the choice
-to use a valid subscription token or pay using a gift voucher. Available since
-protocol **vSUBSCRIBE**.
-
-.. ts:def:: ContractChoice
-
-  interface ContractChoice {
-    // Inputs that must be provided by the customer, if this choice is 
selected.
-    inputs: ContractInput[];
-
-    // Outputs provided by the merchant, if this choice is selected.
-    outputs: ContractOutput[];
-  }
-
-.. ts:def:: ContractInput
-
-  // For now, only token inputs are supported.
-  type ContractInput = ContractInputToken;
-
-.. ts:def:: ContractInputToken
-
-  interface ContractInputToken {
-
-    // Token input.
-    type: "token";
-
-    // How many units of the input are required. Defaults to 1 if not 
specified.
-    // Input with count == 0 are ignored by the merchant backend.
-    count?: Integer;
-
-    // Token family slug as configured in the merchant backend. Slug is unique
-    // across all configured tokens of a merchant.
-    token_family_slug: string;
-
-    // TODO: Is this only relevant for subscriptions or also for discounts?
-    // Start of the validity period of the subscription token. Based on this,
-    // the merchant will select the relevant signing key. Is null for 
discounts.
-    valid_after?: Timestamp;
-
-  }
-
-.. ts:def:: ContractOutput
-
-  type ContractOutput = ContractOutputToken | ContractOutputTaxReceipt;
-
-.. ts:def:: ContractOutputToken
-
-  interface ContractOutputToken {
-
-    // Token output.
-    type: "token";
-
-    // How many units of the output are yielded. Defaults to 1 if not 
specified.
-    // Output with number == 0 are ignored by the merchant backend.
-    number?: Integer;
-
-    // Token family slug as configured in the merchant backend. Slug is unique
-    // across all configured tokens of a merchant.
-    // TODO: Should we rename this to token_family_slug?
-    authority_label: string;
-
-    // TODO: Is this only relevant for subscriptions or also for discounts?
-    // Start of the validity period of the subscription token. Based on this,
-    // the merchant will select the relevant signing key. Is null for 
discounts.
-    valid_after?: Timestamp;
-
-  }
-
-.. ts:def:: ContractOutputTaxReceipt
-
-  interface ContractOutputTaxReceipt {
-
-    // Tax receipt output.
-    type: "tax-receipt";
-
-    // Base URL of the donation authority that will
-    // issue the tax receipt.
-    donau_url: string;
-
-  }
-
 The `Product` object describes the product being purchased from the merchant.
 It has the following structure:
 

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.