[taler-docs] 01/11: add tokenfamilies api to merchant

[gnunet]

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

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

commit 807f2af5879037f15c317fe62056b9493d935fc2
Author: Christian Blättler <blatc2@bfh.ch>
AuthorDate: Tue Oct 24 07:49:09 2023 +0200

    add tokenfamilies api to merchant
---
 core/api-merchant.rst | 214 +++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 211 insertions(+), 3 deletions(-)

diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index 142e83f8..af757225 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -318,7 +318,7 @@ Making the payment
 
       // Custom inputs from the wallet for the contract.
       wallet_data?: Object;
- 
+
       // The session for which the payment is made (or replayed).
       // Only set for session-based payments.
       session_id?: string;
@@ -3311,7 +3311,7 @@ Adding templates
       // The user may specify any amount, but it must be
       // in this currency.
       // This parameter is optional and should not be present
-      // if "amount" is given. 
+      // if "amount" is given.
       currency?: string;
 
       // The price is imposed by the merchant and cannot be changed by the 
customer.
@@ -3512,7 +3512,7 @@ Adding webhooks
     The creation of the webhook is successsful.
 
   :http:statuscode:`404 Not found`:
-    The merchant instance is unknowm or it not in our data.
+    The merchant instance is unknown or it not in our data.
 
   .. ts:def:: WebhookAddDetails
 
@@ -3673,6 +3673,214 @@ Removing webhook
 
 
 
+----------------------------------------
+Token Families: Subscriptions, Discounts
+----------------------------------------
+
+This API provides functionalities for the issuance, management, and revocation
+of token families. Tokens facilitate the implementation of subscriptions and
+discounts, engaging solely the merchant and the user. Each token family
+encapsulates details pertaining to its respective tokens, guiding the 
merchant's
+backend on the appropriate processing and handling.
+
+
+Creating token families
+-----------------------
+
+.. http:post:: [/instances/$INSTANCES]/private/tokenfamilies
+
+  This is used to create a token family.
+
+  **Request:**
+
+  The request must be a `TokenFamilyCreateRequest`.
+
+  **Response:**
+
+  :http:statuscode:`200 OK`:
+    The token family was created successfully. Returns a `TokenFamilyDetails`.
+
+  :http:statuscode:`404 Not found`:
+    The merchant backend is unaware of the instance.
+
+  .. ts:def:: TokenFamilyCreateRequest
+
+    interface TokenFamilyCreateRequest {
+
+      // Human-readable name for the token family.
+      name: string;
+
+      // Human-readable description for the token family.
+      description: string;
+
+      // Optional map from IETF BCP 47 language tags to localized descriptions.
+      description_i18n?: { [lang_tag: string]: string };
+
+      // Start time of the token family's validity period.
+      // If not specified, merchant backend will use the current time.
+      start_time?: Timestamp;
+
+      // End time of the token family's validity period.
+      // If not specified, token family is valid indefinitely.
+      expiration_time?: Timestamp;
+
+      // Validity duration of an issued token.
+      duration: RelativeTime;
+
+      // Kind of the token family.
+      kind: TokenFamilyKind;
+
+   }
+
+  .. ts:def:: TokenFamilyKind
+
+    enum TokenFamilyKind {
+      Discount = "discount",
+      Subscription = "subscription",
+    }
+
+
+Updating token families
+-----------------------
+
+.. http:patch:: [/instances/$INSTANCES]/private/tokenfamilies/$TOKEN_FAMILY_ID
+
+  This is used to update a token family.
+
+  **Request:**
+
+  The request must be a `TokenFamilyUpdateRequest`. Only fields that are not
+  undefined are updated.
+
+  **Response:**
+
+  :http:statuscode:`200 OK`:
+    The token family was successsful updated. Returns a `TokenFamilyDetails`.
+
+  :http:statuscode:`404 Not found`:
+    The merchant backend is unaware of the token family or instance.
+
+  .. ts:def:: TokenFamilyUpdateRequest
+
+    interface TokenFamilyUpdateRequest {
+
+      // Human-readable name for the token family.
+      name?: string;
+
+      // Human-readable description for the token family.
+      description?: string;
+
+      // Optional map from IETF BCP 47 language tags to localized descriptions.
+      description_i18n?: { [lang_tag: string]: string };
+
+      // Validity duration of an issued token.
+      duration?: RelativeTime;
+
+      // Kind of the token family.
+      kind?: TokenFamilyKind;
+
+      // Indicates whether the token family can still issue tokens. Note:
+      // Already issued tokens will be valid, regardless of this setting.
+      can_issue_tokens?: boolean;
+
+   }
+
+
+
+Inspecting token families
+-------------------------
+
+.. http:get:: [/instances/$INSTANCES]/private/tokenfamilies
+
+  This is used to list all configured token families for an instance.
+
+  **Response:**
+
+  :http:statuscode:`200 OK`:
+    The merchant backend has successfully returned all token families.
+    Returns a `TokenFamiliesList`.
+
+  :http:statuscode:`404 Not found`:
+    The merchant backend is unaware of the instance.
+
+  .. ts:def:: TokenFamiliesList
+
+    interface TokenFamiliesList {
+
+      // All configured token families of this instance.
+      token_families: TokenFamilyDetails[];
+
+   }
+
+  The `TokenFamilyDetails` object describes a configured token family.
+
+  .. ts:def:: TokenFamilyDetails
+
+    interface TokenFamilyDetails {
+
+      // Human-readable name for the token family.
+      name: string;
+
+      // Human-readable description for the token family.
+      description: string;
+
+      // Optional map from IETF BCP 47 language tags to localized descriptions.
+      description_i18n?: { [lang_tag: string]: string };
+
+      // Start time of the token family's validity period.
+      start_time: Timestamp;
+
+      // End time of the token family's validity period.
+      expiration: Timestamp;
+
+      // Validity duration of an issued token.
+      duration: RelativeTime;
+
+      // Kind of the token family.
+      kind: TokenFamilyKind;
+
+      // How many tokens have been issued for this family.
+      issued: Integer;
+
+      // How many tokens have been redeemed for this family.
+      redeemed: Integer;
+
+   }
+
+
+.. http:get:: [/instances/$INSTANCES]/private/tokenfamilies/$TOKEN_FAMILY_ID
+
+  This is used to get detailed information about a specific token family.
+
+  **Response:**
+
+  :http:statuscode:`200 OK`:
+    The merchant backend has successfully returned the detailed information
+    about a specific token family. Returns a `TokenFamilyDetails`.
+
+  :http:statuscode:`404 Not found`:
+    The merchant backend is unaware of the token family or instance.
+
+
+
+Deleting token families
+-----------------------
+
+.. http:delete:: [/instances/$INSTANCES]/private/tokenfamilies/$TOKEN_FAMILY_ID
+
+  This is used to delete a token family. Issued tokens of this family will not
+  be spendable anymore.
+
+  **Response:**
+
+  :http:statuscode:`204 No content`:
+    The backend has successfully deleted the token family.
+
+  :http:statuscode:`404 Not found`:
+    The merchant backend is unaware of the token family or instance.
+
+
+
 ------------------
 The Contract Terms
 ------------------

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