diff options
| author | fiatjaf <fiatjaf@gmail.com> | 2023-11-18 09:13:12 -0300 |
|---|---|---|
| committer | fiatjaf <fiatjaf@gmail.com> | 2023-11-18 09:13:12 -0300 |
| commit | 5dcfe85306434f21ecb1e7a47edd92b2e3e64f9a (patch) | |
| tree | 4fff8694238b3ae5e692a8480869ad1266b95be4 /15.md | |
| parent | b0df71824f9967130b54150b64cc70fa94bffec2 (diff) | |
reformat a bunch of json things and small nitpicks.
Diffstat (limited to '15.md')
| -rw-r--r-- | 15.md | 205 |
1 files changed, 107 insertions, 98 deletions
| @@ -1,14 +1,14 @@ | |||
| 1 | NIP-15 | 1 | NIP-15 |
| 2 | ====== | 2 | ====== |
| 3 | 3 | ||
| 4 | Nostr Marketplace (for resilient marketplaces) | 4 | Nostr Marketplace |
| 5 | ----------------------------------- | 5 | ----------------- |
| 6 | 6 | ||
| 7 | `draft` `optional` | 7 | `draft` `optional` |
| 8 | 8 | ||
| 9 | > Based on https://github.com/lnbits/Diagon-Alley | 9 | Based on https://github.com/lnbits/Diagon-Alley. |
| 10 | 10 | ||
| 11 | > Implemented in [NostrMarket](https://github.com/lnbits/nostrmarket) and [Plebeian Market](https://github.com/PlebeianTech/plebeian-market) | 11 | Implemented in [NostrMarket](https://github.com/lnbits/nostrmarket) and [Plebeian Market](https://github.com/PlebeianTech/plebeian-market). |
| 12 | 12 | ||
| 13 | ## Terms | 13 | ## Terms |
| 14 | 14 | ||
| @@ -35,29 +35,30 @@ The `merchant` admin software can be purely clientside, but for `convenience` an | |||
| 35 | A merchant can publish these events: | 35 | A merchant can publish these events: |
| 36 | | Kind | | Description | | 36 | | Kind | | Description | |
| 37 | | --------- | ------------------ | --------------------------------------------------------------------------------------------------------------- | | 37 | | --------- | ------------------ | --------------------------------------------------------------------------------------------------------------- | |
| 38 | | `0 ` | `set_meta` | The merchant description (similar with any `nostr` public key). | | 38 | | `0` | `set_meta` | The merchant description (similar with any `nostr` public key). | |
| 39 | | `30017` | `set_stall` | Create or update a stall. | | 39 | | `30017` | `set_stall` | Create or update a stall. | |
| 40 | | `30018` | `set_product` | Create or update a product. | | 40 | | `30018` | `set_product` | Create or update a product. | |
| 41 | | `4 ` | `direct_message` | Communicate with the customer. The messages can be plain-text or JSON. | | 41 | | `4` | `direct_message` | Communicate with the customer. The messages can be plain-text or JSON. | |
| 42 | | `5 ` | `delete` | Delete a product or a stall. | | 42 | | `5` | `delete` | Delete a product or a stall. | |
| 43 | 43 | ||
| 44 | ### Event `30017`: Create or update a stall. | 44 | ### Event `30017`: Create or update a stall. |
| 45 | 45 | ||
| 46 | **Event Content**: | 46 | **Event Content** |
| 47 | |||
| 47 | ```json | 48 | ```json |
| 48 | { | 49 | { |
| 49 | "id": <String, UUID generated by the merchant. Sequential IDs (`0`, `1`, `2`...) are discouraged>, | 50 | "id": <string, id generated by the merchant. Sequential IDs (`0`, `1`, `2`...) are discouraged>, |
| 50 | "name": <String, stall name>, | 51 | "name": <string, stall name>, |
| 51 | "description": <String (optional), stall description>, | 52 | "description": <string (optional), stall description>, |
| 52 | "currency": <String, currency used>, | 53 | "currency": <string, currency used>, |
| 53 | "shipping": [ | 54 | "shipping": [ |
| 54 | { | 55 | { |
| 55 | "id": <String, UUID of the shipping zone, generated by the merchant>, | 56 | "id": <string, id of the shipping zone, generated by the merchant>, |
| 56 | "name": <String (optional), zone name>, | 57 | "name": <string (optional), zone name>, |
| 57 | "cost": <float, base cost for shipping. The currency is defined at the stall level>, | 58 | "cost": <float, base cost for shipping. The currency is defined at the stall level>, |
| 58 | "regions": [<String, regions included in this zone>], | 59 | "regions": [<string, regions included in this zone>], |
| 59 | } | 60 | } |
| 60 | ] | 61 | ] |
| 61 | } | 62 | } |
| 62 | ``` | 63 | ``` |
| 63 | 64 | ||
| @@ -70,34 +71,39 @@ Fields that are not self-explanatory: | |||
| 70 | - each shipping zone contains the base cost for orders made to that shipping zone, but a specific shipping cost per | 71 | - each shipping zone contains the base cost for orders made to that shipping zone, but a specific shipping cost per |
| 71 | product can also be specified if the shipping cost for that product is higher than what's specified by the base cost. | 72 | product can also be specified if the shipping cost for that product is higher than what's specified by the base cost. |
| 72 | 73 | ||
| 73 | **Event Tags**: | 74 | **Event Tags** |
| 75 | |||
| 74 | ```json | 76 | ```json |
| 75 | "tags": [["d", <String, id of stall]] | 77 | { |
| 78 | "tags": [["d", <string, id of stall]], | ||
| 79 | ... | ||
| 80 | } | ||
| 76 | ``` | 81 | ``` |
| 77 | - the `d` tag is required, its value MUST be the same as the stall `id`. | 82 | - the `d` tag is required, its value MUST be the same as the stall `id`. |
| 78 | 83 | ||
| 79 | ### Event `30018`: Create or update a product | 84 | ### Event `30018`: Create or update a product |
| 80 | 85 | ||
| 81 | **Event Content**: | 86 | **Event Content** |
| 87 | |||
| 82 | ```json | 88 | ```json |
| 83 | { | 89 | { |
| 84 | "id": <String, UUID generated by the merchant.Sequential IDs (`0`, `1`, `2`...) are discouraged>, | 90 | "id": <string, id generated by the merchant (sequential ids are discouraged)>, |
| 85 | "stall_id": <String, UUID of the stall to which this product belong to>, | 91 | "stall_id": <string, id of the stall to which this product belong to>, |
| 86 | "name": <String, product name>, | 92 | "name": <string, product name>, |
| 87 | "description": <String (optional), product description>, | 93 | "description": <string (optional), product description>, |
| 88 | "images": <[String], array of image URLs, optional>, | 94 | "images": <[string], array of image URLs, optional>, |
| 89 | "currency": <String, currency used>, | 95 | "currency": <string, currency used>, |
| 90 | "price": <float, cost of product>, | 96 | "price": <float, cost of product>, |
| 91 | "quantity": <int or null, available items>, | 97 | "quantity": <int or null, available items>, |
| 92 | "specs": [ | 98 | "specs": [ |
| 93 | [<String, spec key>, <String, spec value>] | 99 | [<string, spec key>, <string, spec value>] |
| 94 | ], | 100 | ], |
| 95 | "shipping": [ | 101 | "shipping": [ |
| 96 | { | 102 | { |
| 97 | "id": <String, UUID of the shipping zone. Must match one of the zones defined for the stall>, | 103 | "id": <string, id of the shipping zone (must match one of the zones defined for the stall)>, |
| 98 | "cost": <float, extra cost for shipping. The currency is defined at the stall level>, | 104 | "cost": <float, extra cost for shipping. The currency is defined at the stall level>, |
| 99 | } | 105 | } |
| 100 | ] | 106 | ] |
| 101 | } | 107 | } |
| 102 | ``` | 108 | ``` |
| 103 | 109 | ||
| @@ -114,16 +120,18 @@ Fields that are not self-explanatory: | |||
| 114 | - the `id` should match the id of the shipping zone, as defined in the `shipping` field of the stall | 120 | - the `id` should match the id of the shipping zone, as defined in the `shipping` field of the stall |
| 115 | - 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: | 121 | - 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: |
| 116 | - the `base cost from the stall` for the chosen shipping option | 122 | - the `base cost from the stall` for the chosen shipping option |
| 117 | - the result of multiplying the product units by the `shipping costs specified in the product`, if any. | 123 | - the result of multiplying the product units by the `shipping costs specified in the product`, if any. |
| 124 | |||
| 125 | **Event Tags** | ||
| 118 | 126 | ||
| 119 | **Event Tags**: | ||
| 120 | ```json | 127 | ```json |
| 121 | "tags": [ | 128 | "tags": [ |
| 122 | ["d", <String, id of product], | 129 | ["d", <string, id of product], |
| 123 | ["t", <String (optional), product category], | 130 | ["t", <string (optional), product category], |
| 124 | ["t", <String (optional), product category], | 131 | ["t", <string (optional), product category], |
| 125 | ... | 132 | ... |
| 126 | ] | 133 | ], |
| 134 | ... | ||
| 127 | ``` | 135 | ``` |
| 128 | 136 | ||
| 129 | - the `d` tag is required, its value MUST be the same as the product `id`. | 137 | - the `d` tag is required, its value MUST be the same as the product `id`. |
| @@ -147,23 +155,23 @@ The below json goes in content of [NIP04](https://github.com/nostr-protocol/nips | |||
| 147 | 155 | ||
| 148 | ```json | 156 | ```json |
| 149 | { | 157 | { |
| 150 | "id": <String, UUID generated by the customer>, | 158 | "id": <string, id generated by the customer>, |
| 151 | "type": 0, | 159 | "type": 0, |
| 152 | "name": <String (optional), ???>, | 160 | "name": <string (optional), ???>, |
| 153 | "address": <String (optional), for physical goods an address should be provided> | 161 | "address": <string (optional), for physical goods an address should be provided> |
| 154 | "message": "<String (optional), message for merchant>, | 162 | "message": "<string (optional), message for merchant>, |
| 155 | "contact": { | 163 | "contact": { |
| 156 | "nostr": <32-bytes hex of a pubkey>, | 164 | "nostr": <32-bytes hex of a pubkey>, |
| 157 | "phone": <String (optional), if the customer wants to be contacted by phone>, | 165 | "phone": <string (optional), if the customer wants to be contacted by phone>, |
| 158 | "email": <String (optional), if the customer wants to be contacted by email>, | 166 | "email": <string (optional), if the customer wants to be contacted by email>, |
| 159 | }, | 167 | }, |
| 160 | "items": [ | 168 | "items": [ |
| 161 | { | 169 | { |
| 162 | "product_id": <String, UUID of the product>, | 170 | "product_id": <string, id of the product>, |
| 163 | "quantity": <int, how many products the customer is ordering> | 171 | "quantity": <int, how many products the customer is ordering> |
| 164 | } | 172 | } |
| 165 | ], | 173 | ], |
| 166 | "shipping_id": <String, UUID of the shipping zone> | 174 | "shipping_id": <string, id of the shipping zone> |
| 167 | } | 175 | } |
| 168 | 176 | ||
| 169 | ``` | 177 | ``` |
| @@ -186,23 +194,23 @@ The below json goes in `content` of [NIP04](https://github.com/nostr-protocol/ni | |||
| 186 | 194 | ||
| 187 | ```json | 195 | ```json |
| 188 | { | 196 | { |
| 189 | "id": <String, UUID of the order>, | 197 | "id": <string, id of the order>, |
| 190 | "type": 1, | 198 | "type": 1, |
| 191 | "message": <String, message to customer, optional>, | 199 | "message": <string, message to customer, optional>, |
| 192 | "payment_options": [ | 200 | "payment_options": [ |
| 193 | { | 201 | { |
| 194 | "type": <String, option type>, | 202 | "type": <string, option type>, |
| 195 | "link": <String, url, btc address, ln invoice, etc> | 203 | "link": <string, url, btc address, ln invoice, etc> |
| 196 | }, | 204 | }, |
| 197 | { | 205 | { |
| 198 | "type": <String, option type>, | 206 | "type": <string, option type>, |
| 199 | "link": <String, url, btc address, ln invoice, etc> | 207 | "link": <string, url, btc address, ln invoice, etc> |
| 200 | }, | 208 | }, |
| 201 | { | 209 | { |
| 202 | "type": <String, option type>, | 210 | "type": <string, option type>, |
| 203 | "link": <String, url, btc address, ln invoice, etc> | 211 | "link": <string, url, btc address, ln invoice, etc> |
| 204 | } | 212 | } |
| 205 | ] | 213 | ] |
| 206 | } | 214 | } |
| 207 | ``` | 215 | ``` |
| 208 | 216 | ||
| @@ -214,11 +222,11 @@ The below json goes in `content` of [NIP04](https://github.com/nostr-protocol/ni | |||
| 214 | 222 | ||
| 215 | ```json | 223 | ```json |
| 216 | { | 224 | { |
| 217 | "id": <String, UUID of the order>, | 225 | "id": <string, id of the order>, |
| 218 | "type": 2, | 226 | "type": 2, |
| 219 | "message": <String, message to customer>, | 227 | "message": <string, message to customer>, |
| 220 | "paid": <Bool, true/false has received payment>, | 228 | "paid": <bool: has received payment>, |
| 221 | "shipped": <Bool, true/false has been shipped>, | 229 | "shipped": <bool: has been shipped>, |
| 222 | } | 230 | } |
| 223 | ``` | 231 | ``` |
| 224 | ## Customize Marketplace | 232 | ## Customize Marketplace |
| @@ -226,19 +234,20 @@ Create a customized user experience using the `naddr` from [NIP-19](https://gith | |||
| 226 | 234 | ||
| 227 | ### Event `30019`: Create or update marketplace UI/UX | 235 | ### Event `30019`: Create or update marketplace UI/UX |
| 228 | 236 | ||
| 229 | **Event Content**: | 237 | **Event Content** |
| 238 | |||
| 230 | ```json | 239 | ```json |
| 231 | { | 240 | { |
| 232 | "name": <String (optional), market name>, | 241 | "name": <string (optional), market name>, |
| 233 | "about": <String (optional), market description>, | 242 | "about": <string (optional), market description>, |
| 234 | "ui": { | 243 | "ui": { |
| 235 | "picture": <String (optional), market logo image URL>, | 244 | "picture": <string (optional), market logo image URL>, |
| 236 | "banner": <String (optional), market logo banner URL>, | 245 | "banner": <string (optional), market logo banner URL>, |
| 237 | "theme": <String (optional), market theme>, | 246 | "theme": <string (optional), market theme>, |
| 238 | "darkMode": <Bool, true/false> | 247 | "darkMode": <bool, true/false> |
| 239 | }, | 248 | }, |
| 240 | "merchants": <[String] (optional), array of pubkeys>, | 249 | "merchants": [array of pubkeys (optional)], |
| 241 | ... | 250 | ... |
| 242 | } | 251 | } |
| 243 | ``` | 252 | ``` |
| 244 | 253 | ||