upleb.uk

Public git repos — served from a NIP-34 GRASP relay at git.upleb.uk

summaryrefslogtreecommitdiff
path: root/15.md
diff options
context:
space:
mode:
authorfiatjaf <fiatjaf@gmail.com>2023-11-18 09:13:12 -0300
committerfiatjaf <fiatjaf@gmail.com>2023-11-18 09:13:12 -0300
commit5dcfe85306434f21ecb1e7a47edd92b2e3e64f9a (patch)
tree4fff8694238b3ae5e692a8480869ad1266b95be4 /15.md
parentb0df71824f9967130b54150b64cc70fa94bffec2 (diff)
reformat a bunch of json things and small nitpicks.
Diffstat (limited to '15.md')
-rw-r--r--15.md205
1 files changed, 107 insertions, 98 deletions
diff --git a/15.md b/15.md
index 0ee000f..51b7792 100644
--- a/15.md
+++ b/15.md
@@ -1,14 +1,14 @@
1NIP-15 1NIP-15
2====== 2======
3 3
4Nostr Marketplace (for resilient marketplaces) 4Nostr Marketplace
5----------------------------------- 5-----------------
6 6
7`draft` `optional` 7`draft` `optional`
8 8
9> Based on https://github.com/lnbits/Diagon-Alley 9Based 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) 11Implemented 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
35A merchant can publish these events: 35A 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