Document review API

source/includes/resources/purchases.md

@@ -61,20 +61,24 @@ The Purchase will change to the **"buyer_pending"** stage. A 21 day timer will s
 > To mark a purchase as received
 
 ```javascript
-const transaction = await origin.purchases.buyerConfirmReceipt(purchaseAddress)
+const review = {rating: 5, reviewText: "Prompt shipping!" }
+const transaction = await origin.purchases.buyerConfirmReceipt(purchaseAddress, review)
 await transaction.isFinished()
 ```
 
 This method is **called by the buyer** when the Purchase is in the **"buyer_pending"** stage.
 
 The Purchase will change to the **"seller_pending"** stage.
 
+A rating from 1 to 5 is required as a part of a review. Review text is optional.
+
 ## sellerGetPayout
 
 > To mark a purchase as received
 
 ```javascript
-const transaction = await origin.purchases.sellerGetPayout(purchaseAddress)
+const review = {rating: 5, reviewText: "Good buyer!" }
+const transaction = await origin.purchases.sellerGetPayout(purchaseAddress, review)
 await transaction.isFinished()
 ```
 
@@ -84,6 +88,8 @@ The seller will receive all eth value on the contract.
 
 The Purchase will change to the **"complete"** stage.
 
+A rating from 1 to 5 is required as a part of a review. Review text is optional.
+
 ## getLogs
 
 > To get the transaction logs for a purchase

source/includes/resources/reviews.md

@@ -0,0 +1,47 @@
+# Review
+
+Reviews are created by the buyer in the [receipt](/#purchase-buyerconfirmreceipt) stage and by the seller in the [payout](#purchase-sellergetpayout) stage of the purchase process. A review consists of a required 1-5 rating and an optional reviewText text field.
+
+## find
+
+> To lookup reviews
+
+```javascript
+const purchaseAddress = "0x521b8d5f9e432e6b23d79fac02e5792eb8746ce1"
+const reviews = await origin.reviews.find({purchaseAddress: purchaseAddress})
+// Returns 
+[{
+    blockHash: "0xf8d740a4eb381f99c259129da68df30b6a63cb3596839b4b40f01e8e4b55821b",
+    blockNumber: 20,
+    ipfsHash: undefined,
+    purchaseAddress: "0x521b8d5f9e432e6b23d79fac02e5792eb8746ce1",
+    rating: 5,
+    reviewText: "",
+    revieweeAddress: "0x627306090abaB3A6e1400e9345bC60c78a8BEf57",
+    revieweeRole: "BUYER",
+    reviewerAddress: "0x821aEa9a577a9b44299B9c15c88cf3087F3b5544",
+    timestamp: 1526496009,
+    transactionHash: "0x94642427369cc50cee75a92df128c654c7d62b644d6c00f76e2404eadadf38bb"
+},
+{
+    rating: 5,
+    reviewText: "Very quick payment",
+    blockHash: "0xcce740a4eb381f99c259129da68df30b6a63cb3596839b4b40f01e8e4b55821b",
+    blockNumber: 220,
+    ipfsHash: "QmfXRgtSbrGggApvaFCa88ofeNQP79G18DpWaSW1Wya1u8",
+    purchaseAddress: "0x521b8d5f9e432e6b23d79fac02e5792eb8746ce1",
+    revieweeAddress: "0x821aEa9a577a9b44299B9c15c88cf3087F3b5544",
+    revieweeRole: "SELLER",
+    reviewerAddress: "0x627306090abaB3A6e1400e9345bC60c78a8BEf57",
+    timestamp: 1526496009,
+    transactionHash: "0xAC642427369cc50cee75a92df128c654c7d62b644d6c00f76e2404eadadfr91a"
+}]
+```
+
+You can find reviews with the following filter options:
+
+- `purchaseAddress`
+- `userAddress` - support coming soon
+- `sellerAddress` - support coming soon
+- `buyerAddress` - support coming soon
+- `listingAddress` - support coming soon

source/index.html.md

@@ -18,6 +18,7 @@ includes:
   - resources/attestations
   - resources/listings
   - resources/purchases
+  - resources/reviews
   - resources/users
   - listing_schemas
   - getting_help