Merge branch 'master' into clarify-json-serialization

1 files changed, 140 insertions, 92 deletions

diff --git a/15.md b/15.md
index f8df328..51b7792 100644
--- a/15.md
+++ b/15.md
@@ -1,14 +1,14 @@
 NIP-15
 ======
 
-Nostr Marketplace (for resilient marketplaces)
------------------------------------
+Nostr Marketplace
+-----------------
 
-`draft` `optional` `author:fiatjaf` `author:benarc`  `author:motorina0` `author:talvasconcelos` 
+`draft` `optional`
 
-> Based on https://github.com/lnbits/Diagon-Alley
+Based on https://github.com/lnbits/Diagon-Alley.
 
-> Implemented here https://github.com/lnbits/nostrmarket
+Implemented in [NostrMarket](https://github.com/lnbits/nostrmarket) and [Plebeian Market](https://github.com/PlebeianTech/plebeian-market).
 
 ## Terms
 
@@ -33,84 +33,109 @@ The `merchant` admin software can be purely clientside, but for `convenience` an
 ## `Merchant` publishing/updating products (event)
 
 A merchant can publish these events:
-| Kind    |                  | Description                                                                                                   | NIP                                     |
-|---------|------------------|---------------------------------------------------------------------------------------------------------------|-----------------------------------------|
-| `0    ` | `set_meta`       | The merchant description (similar with any `nostr` public key).                                               | [NIP01       ](https://github.com/nostr-protocol/nips/blob/master/01.md)                            |
-| `30017` | `set_stall`      | Create or update a stall.                                                                                     | [NIP33](https://github.com/nostr-protocol/nips/blob/master/33.md) (Parameterized Replaceable Event) |
-| `30018` | `set_product`    | Create or update a product.                                                                                   | [NIP33](https://github.com/nostr-protocol/nips/blob/master/33.md) (Parameterized Replaceable Event) |
-| `4    ` | `direct_message` | Communicate with the customer. The messages can be plain-text or JSON. | [NIP04](https://github.com/nostr-protocol/nips/blob/master/04.md)                                            |
-| `5    ` | `delete`         | Delete a product or a stall.                                                                                  | [NIP09](https://github.com/nostr-protocol/nips/blob/master/09.md)                                   |
+| Kind      |                    | Description                                                                                                     |
+| --------- | ------------------ | --------------------------------------------------------------------------------------------------------------- |
+| `0`       | `set_meta`         | The merchant description (similar with any `nostr` public key).                                                 |
+| `30017`   | `set_stall`        | Create or update a stall.                                                                                       |
+| `30018`   | `set_product`      | Create or update a product.                                                                                     |
+| `4`       | `direct_message`   | Communicate with the customer. The messages can be plain-text or JSON.                                          |
+| `5`       | `delete`           | Delete a product or a stall.                                                                                    |
 
 ### Event `30017`: Create or update a stall.
 
-**Event Content**:
+**Event Content**
+
 ```json
 {
-    "id": <String, UUID generated by the merchant. Sequential IDs (`0`, `1`, `2`...) are discouraged>,
-    "name": <String, stall name>,
-    "description": <String (optional), stall description>,
-    "currency": <String, currency used>,
-    "shipping": [
-        {
-            "id": <String, UUID of the shipping zone, generated by the merchant>,
-            "name": <String (optional), zone name>,
-            "cost": <float, cost for shipping. The currency is defined at the stall level>,
-            "countries": [<String, countries included in this zone>],
-        }
-    ]
+  "id": <string, id generated by the merchant. Sequential IDs (`0`, `1`, `2`...) are discouraged>,
+  "name": <string, stall name>,
+  "description": <string (optional), stall description>,
+  "currency": <string, currency used>,
+  "shipping": [
+    {
+      "id": <string, id of the shipping zone, generated by the merchant>,
+      "name": <string (optional), zone name>,
+      "cost": <float, base cost for shipping. The currency is defined at the stall level>,
+      "regions": [<string, regions included in this zone>],
+    }
+  ]
 }
 ```
 
 Fields that are not self-explanatory:
  - `shipping`:
-   - an array with possible shipping zones for this stall. The customer MUST choose exactly one shipping zone.
+   - an array with possible shipping zones for this stall.
+   - the customer MUST choose exactly one of those shipping zones.
    - shipping to different zones can have different costs. For some goods (digital for example) the cost can be zero.
    - the `id` is an internal value used by the merchant. This value must be sent back as the customer selection.
+   - each shipping zone contains the base cost for orders made to that shipping zone, but a specific shipping cost per
+   product can also be specified if the shipping cost for that product is higher than what's specified by the base cost.
+
+**Event Tags**
 
-**Event Tags**:
 ```json
-  "tags": [["d", <String, id of stall]]
+{
+  "tags": [["d", <string, id of stall]],
+  ...
+}
 ```
- - the `d` tag is required by [NIP33](https://github.com/nostr-protocol/nips/blob/master/33.md). 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`.
 
 ### Event `30018`: Create or update a product
 
-**Event Content**:
+**Event Content**
+
 ```json
 {
-    "id": <String, UUID generated by the merchant.Sequential IDs (`0`, `1`, `2`...) are discouraged>,
-    "stall_id": <String, UUID of the stall to which this product belong to>,
-    "name": <String, product name>,
-    "description": <String (optional), product description>,
-    "images": <[String], array of image URLs, optional>,
-    "currency": <String, currency used>,
-    "price": <float, cost of product>,
-    "quantity": <int, available items>,
-    "specs": [
-      [ <String, spec key>, <String, spec value>]
-     ]
+  "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>,
+  "description": <string (optional), product description>,
+  "images": <[string], array of image URLs, optional>,
+  "currency": <string, currency used>,
+  "price": <float, cost of product>,
+  "quantity": <int or null, available items>,
+  "specs": [
+    [<string, spec key>, <string, spec value>]
+  ],
+  "shipping": [
+    {
+      "id": <string, id of the shipping zone (must match one of the zones defined for the stall)>,
+      "cost": <float, extra cost for shipping. The currency is defined at the stall level>,
+    }
+  ]
 }
 ```
 
 Fields that are not self-explanatory:
+ - `quantity` can be null in the case of items with unlimited abailability, like digital items, or services
  - `specs`:
-   - an array of key pair values. It allows for the Customer UI to present present product specifications in a structure mode. It also allows comparison between products
+   - 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"]]`
 
-_Open_: better to move `spec` in the `tags` section of the event?
+    _Open_: better to move `spec` in the `tags` section of the event?
+
+- `shipping`:
+   - an _optional_ array of extra costs to be used per shipping zone, only for products that require special shipping costs to be added to the base shipping cost defined in the stall
+   - the `id` should match the id of the shipping zone, as defined in the `shipping` field of the stall
+   - 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.
+
+**Event Tags**
 
-**Event Tags**:
 ```json
   "tags": [
-       ["d", <String, id of product],
-       ["t", <String (optional), product category],
-       ["t", <String (optional), product category],
-       ...
-    ]
+    ["d", <string, id of product],
+    ["t", <string (optional), product category],
+    ["t", <string (optional), product category],
+    ...
+  ],
+  ...
 ```
 
- - the `d` tag is required by [NIP33](https://github.com/nostr-protocol/nips/blob/master/33.md). Its value MUST be the same as the product `id`.
- - the `t` tag is as searchable tag ([NIP12](https://github.com/nostr-protocol/nips/blob/master/12.md)). It represents different categories that the product can be part of (`food`, `fruits`). Multiple `t` tags can be present.
+ - the `d` tag is required, its value MUST be the same as the product `id`.
+ - 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.
 
 ## Checkout events
 
@@ -130,29 +155,29 @@ The below json goes in content of [NIP04](https://github.com/nostr-protocol/nips
 
 ```json
 {
-    "id": <String, UUID generated by the customer>,
-    "type": 0,
-    "name": <String (optional), ???>,
-    "address": <String (optional), for physical goods an address should be provided>
-    "message": "<String (optional), message for merchant>,
-    "contact": {
-        "nostr": <32-bytes hex of a pubkey>,
-        "phone": <String (optional), if the customer wants to be contacted by phone>,
-        "email": <String (optional), if the customer wants to be contacted by email>,
-    },
-    "items": [
-        {
-            "product_id": <String, UUID of the product>,
-            "quantity": <int, how many products the customer is ordering>
-        }
-    ],
-    "shipping_id": <String, UUID of the shipping zone>
+  "id": <string, id generated by the customer>,
+  "type": 0,
+  "name": <string (optional), ???>,
+  "address": <string (optional), for physical goods an address should be provided>
+  "message": "<string (optional), message for merchant>,
+  "contact": {
+    "nostr": <32-bytes hex of a pubkey>,
+    "phone": <string (optional), if the customer wants to be contacted by phone>,
+    "email": <string (optional), if the customer wants to be contacted by email>,
+  },
+  "items": [
+    {
+      "product_id": <string, id of the product>,
+      "quantity": <int, how many products the customer is ordering>
+    }
+  ],
+  "shipping_id": <string, id of the shipping zone>
 }
 
 ```
 
 _Open_: is `contact.nostr` required?
-  
+
 
 ### Step 2: `merchant` request payment (event)
 
@@ -169,23 +194,23 @@ The below json goes in `content` of [NIP04](https://github.com/nostr-protocol/ni
 
 ```json
 {
-    "id": <String, UUID of the order>,
-    "type": 1,
-    "message": <String, message to customer, optional>,
-    "payment_options": [
-        {
-            "type": <String, option type>,
-            "link": <String, url, btc address, ln invoice, etc>
-        },
-        {
-            "type": <String, option type>,
-            "link": <String, url, btc address, ln invoice, etc>
-        },
-                {
-            "type": <String, option type>,
-            "link": <String, url, btc address, ln invoice, etc>
-        }
-    ]
+  "id": <string, id of the order>,
+  "type": 1,
+  "message": <string, message to customer, optional>,
+  "payment_options": [
+    {
+      "type": <string, option type>,
+      "link": <string, url, btc address, ln invoice, etc>
+    },
+    {
+      "type": <string, option type>,
+      "link": <string, url, btc address, ln invoice, etc>
+    },
+    {
+      "type": <string, option type>,
+      "link": <string, url, btc address, ln invoice, etc>
+    }
+  ]
 }
 ```
 
@@ -197,13 +222,36 @@ The below json goes in `content` of [NIP04](https://github.com/nostr-protocol/ni
 
 ```json
 {
-    "id": <String, UUID of the order>,
-    "type": 2,
-    "message": <String, message to customer>,
-    "paid": <Bool, true/false has received payment>,
-    "shipped": <Bool, true/false has been shipped>,
+  "id": <string, id of the order>,
+  "type": 2,
+  "message": <string, message to customer>,
+  "paid": <bool: has received payment>,
+  "shipped": <bool: has been shipped>,
 }
 ```
+## Customize Marketplace
+Create a customized user experience using the `naddr` from [NIP-19](https://github.com/nostr-protocol/nips/blob/master/19.md#shareable-identifiers-with-extra-metadata). The use of `naddr` enables easy sharing of marketplace events while incorporating a rich set of metadata. This metadata can include relays, merchant profiles, and more. Subsequently, it allows merchants to be grouped into a market, empowering the market creator to configure the marketplace's user interface and user experience, and share that marketplace. This customization can encompass elements such as market name, description, logo, banner, themes, and even color schemes, offering a tailored and unique marketplace experience.
+
+### Event `30019`: Create or update marketplace UI/UX
+
+**Event Content**
+
+```json
+{
+  "name": <string (optional), market name>,
+  "about": <string (optional), market description>,
+  "ui": {
+    "picture": <string (optional), market logo image URL>,
+    "banner": <string (optional), market logo banner URL>,
+    "theme": <string (optional), market theme>,
+    "darkMode": <bool, true/false>
+  },
+  "merchants": [array of pubkeys (optional)],
+  ...
+}
+```
+
+This event leverages naddr to enable comprehensive customization and sharing of marketplace configurations, fostering a unique and engaging marketplace environment.
 
 ## Customer support events
 
@@ -211,4 +259,4 @@ Customer support is handled over whatever communication method was specified. If
 
 ## Additional
 
-Standard data models can be found here <a href="https://raw.githubusercontent.com/lnbits/nostrmarket/main/models.py">here</a>
+Standard data models can be found <a href="https://raw.githubusercontent.com/lnbits/nostrmarket/main/models.py">here</a>