variable products, modifications, and comments

15.md

@@ -79,7 +79,7 @@ Fields that are not self-explanatory:
   ...
 }
 ```
- - the `d` tag is required, its value MUST be the same as the stall `id`.
+ - the `d` tag is required, its value MUST be the same as the stall `id`. (NOTE: What is the reason for having the same value of `id` in the content, and `d` tag? Can we get rid of the `id` and just have the `d` tag?)
 
 ### Event `30018`: Create or update a product
 
@@ -90,6 +90,7 @@ Fields that are not self-explanatory:
   "id": <string, id generated by the merchant (sequential ids are discouraged)>,
   "stall_id": <string, id of the stall to which this product belong to>,
   "name": <string, product name>,
+  "type": <simple | variable | variation>,
   "description": <string (optional), product description>,
   "images": <[string], array of image URLs, optional>,
   "currency": <string, currency used>,
@@ -108,7 +109,7 @@ Fields that are not self-explanatory:
 ```
 
 Fields that are not self-explanatory:
- - `quantity` can be null in the case of items with unlimited availability, like digital items, or services
+ - `quantity`: can be null in the case of items with unlimited availability, like digital items, or services
  - `specs`:
    - an optional array of key pair values. It allows for the Customer UI to present product specifications in a structure mode. It also allows comparison between products
    - eg: `[["operating_system", "Android 12.0"], ["screen_size", "6.4 inches"], ["connector_type", "USB Type C"]]`
@@ -121,12 +122,14 @@ Fields that are not self-explanatory:
    - to calculate the total cost of shipping for an order, the user will choose a shipping option during checkout, and then the client must consider this costs:
      - the `base cost from the stall` for the chosen shipping option
      - the result of multiplying the product units by the `shipping costs specified in the product`, if any.
+- `type`: It determines whether a product is a simple product, a variable product, or a variation of a variable product. (i.e.: a shirt sold in a single colour is a simple product, a shirt sold in more than one colour is a variable product, and has variations). To link the variable product within its variations, the variation product event should contain an `a` tag pointing to the event coordinate of the variable product. 
 
 **Event Tags**
 
 ```json
   "tags": [
     ["d", <string, id of product],
+    ["a", <event coordinate (naddr) of the variable product (optional, only for variations)>],
     ["t", <string (optional), product category],
     ["t", <string (optional), product category],
     ...
@@ -134,8 +137,9 @@ Fields that are not self-explanatory:
   ...
 ```
 
- - the `d` tag is required, its value MUST be the same as the product `id`.
+ - The `d` tag is required, its value MUST be the same as the product `id`.(NOTE: What is the reason for having the same value of `id` in the content, and `d` tag? Can we get rid of the `id` and just have the `d` tag?)
- - the `t` tag is as searchable tag, it represents different categories that the product can be part of (`food`, `fruits`). Multiple `t` tags can be present.
+ - The `t` tag is as searchable tag, it represents different categories that the product can be part of (`food`, `fruits`). Multiple `t` tags can be present.
+ - The `a` tag is used in variation products. It is used to link products that belong to a variable product.
 
 ## Checkout events
 
@@ -223,11 +227,19 @@ The below JSON goes in `content` of [NIP-04](https://github.com/nostr-protocol/n
 {
   "id": <string, id of the order>,
   "type": 2,
+  "status":<String, "pending" | "processing" | "completed" | "cancelled" | "refunded" | "failed">;,
   "message": <string, message to customer>,
   "paid": <bool: has received payment>,
   "shipped": <bool: has been shipped>,
 }
 ```
+Possible order statuses meaning:
+- Pending - The order has been created there is something that maintains it on hold, i.e: payment has not been received yet, or the stock of the product has been reduced but the merchant needs to approve the payment.
+- Processing - The payment has been received and the order is awaiting fulfillment (i.e. shipping products)
+- Completed - The payment is successful and the order has been fulfilled.
+- Cancelled - The order has been manually cancelled by the admin or the customer.
+- Refunded - The order has been refunded by the admin.
+- Failed - The order has failed due to technical issues or the payment being declined.
 
 ## Customize Marketplace
 
@@ -293,7 +305,7 @@ This event leverages naddr to enable comprehensive customization and sharing of
 ```json
 {
     "content": <int, amount of sats>,
-    "tags": [["e", <event ID of the auction to bid on>]],
+    "tags": [["e", <event ID of the auction to bid on>]],//NOTE: Tag "e" should be "a" since products are kind:30020 ?
 }
 ```
 
@@ -302,6 +314,18 @@ Bids are simply events of kind `1021` with a `content` field specifying the amou
 > [!NOTE]
 > Auctions can be edited as many times as desired (they are "parameterized replaceable events") by the author - even after the start_date, but they cannot be edited after they have received the first bid! This is enforced by the fact that bids reference the event ID of the auction (rather than the product UUID), which changes with every new version of the auctioned product. So a bid is always attached to one "version". Editing the auction after a bid would result in the new product losing the bid! 
 
+(NOTE: Should the bid event contain a stringified version of the kind:30020 auction event that its bidding for? in order to have a snapshot of it that can be verified with the signature, and not relay in the tag:`e` id of a parametriced replaceable event since its not mandatory that relays stores it. Stringified version of the auction event can be on the content field, and amount in sats using a tag:`amount` as its standariced in the protocol)
+
+```json
+{
+    "content": <stringified auction event>,
+    "tags": [
+      ["a", <event coordinate of the auction to bid on>],
+      ["amount": <int, in the currency of the auction>]
+    ]
+}
+```
+Bids are simply events of kind `1021` with a `content` field containing the strigified version of the auction event, and tags consisting of a tag:`a` pointing to the auction event coordinates and a tag:`amount` containing the bid amount expressed as an integer in the auction currency. Bids must refer to an auction.
 ### Event `1022`: Bid confirmation
 
 **Event Content**:
@@ -310,7 +334,7 @@ Bids are simply events of kind `1021` with a `content` field specifying the amou
 {
     "status": <String, "accepted" | "rejected" | "pending" | "winner">,
     "message": <String (optional)>,
-    "duration_extended": <int (optional), number of seconds>
+    "duration_extended": <int (optional), number of seconds>//NOTE: Is this necessary? It can be simplified by simply increasing the duration of the kind:30020 auction event.
 }
 ```
 
@@ -323,7 +347,7 @@ Bids should be confirmed by the merchant before being considered as valid by oth
 
 The `content` field is a JSON which includes *at least* a `status`. `winner` is how the *winning bid* is replied to after the auction ends and the winning bid is picked by the merchant.
 
-The reasons for which a bid can be marked as `rejected` or `pending` are up to the merchant's implementation and configuration - they could be anything from basic validation errors (amount too low) to the bidder being blacklisted or to the bidder lacking sufficient *trust*, which could lead to the bid being marked as `pending` until sufficient verification is performed. The difference between the two is that `pending` bids *might* get approved after additional steps are taken by the bidder, whereas `rejected` bids can not be later approved.
+The reasons for which a bid can be marked as `rejected` or `pending` are up to the merchant's implementation and configuration - they could be anything from basic validation errors (amount too low) to the bidder being blacklisted or to the bidder lacking sufficient *trust*, which could lead to the bid being marked as `pending` until sufficient verification is performed. The difference between the two is that `pending` bids *might* get approved after additional steps are taken by the bidder, whereas `rejected` bids can not be later approved. (NOTE: pending action can happen again after and update of the auction event, the merchant dedices publish an update in the starting bid field of the auction event and can mark as pending bid that have a lower value)
 
 An additional `message` field can appear in the `content` JSON to give further context as of why a bid is `rejected` or `pending`.