Rename country data & improve documentation

KirianCaumes · Nov 30, 2022 · 1612e90 · 1612e90
1 parent f1a0415
commit 1612e90
Show file tree

Hide file tree

Showing 4 changed files with 108 additions and 43 deletions.
diff --git a/README.MD b/README.MD
@@ -2,46 +2,116 @@
 
 Another (better ?) NodeJs library to fetch data from Discogs marketplace. 💿
 
-## Installing (with npm)
+## Installation (with npm)
+
+Run the following command in your project:
 
 ```sh
 npm install discogs-marketplace-api-nodejs
 ```
 
-## Example
+## Quick Start
+
+Import `DiscogsMarketplace` into your project:
+
+```js
+// With ECMAScript 6 and +
+import DiscogsMarketplace from 'discogs-marketplace-api-nodejs'
+
+// With CommonJS
+const DiscogsMarketplace = require('discogs-marketplace-api-nodejs').default
+```
+
+## Examples
 
-With ECMAScript 6 and +
+- Get top 250 items, of the 2nd page, filtered by Rock, listed by newest, for a given artist
 
 ```js
 import DiscogsMarketplace, { EType } from 'discogs-marketplace-api-nodejs'
 
-DiscogsMarketplace.search({ searchType: EType.ARTIST, searchValue: 244819 })
-    .then(res => {
-        console.log(res) // See 'Data format' chapter
-    })
-    .catch(err => {
-        console.error(err) // See 'Data format' chapter
-    })
+// https://www.discogs.com/sell/list?sort=listed,desc&limit=250&artist_id=244819&page=2&genre=Rock
+const result = await DiscogsMarketplace.search({
+    limit: 250,
+    page: 2,
+    genre: EGenre.ROCK,
+    sort: ESort.LISTED_NEWEST,
+    searchType: EType.ARTIST,
+    searchValue: 244819,
+})
 ```
 
-With CommonJS
+- Get top 50 items, of the 1st page, listed by price lowest, on a user wantlist
 
 ```js
-const DiscogsMarketplace = require('discogs-marketplace-api-nodejs').default
-const { EType } = require('discogs-marketplace-api-nodejs')
-
-DiscogsMarketplace.search({ searchType: EType.ARTIST, searchValue: 244819 })
-    .then(res => {
-        console.log(res) // See 'Data format' chapter
-    })
-    .catch(err => {
-        console.error(err) // See 'Data format' chapter
-    })
+import DiscogsMarketplace, { EType } from 'discogs-marketplace-api-nodejs'
+
+// https://www.discogs.com/sell/mywants?limit=50&user=Kirian_&sort=price,asc
+const result = await DiscogsMarketplace.search({
+    limit: 50,
+    sort: ESort.PRICE_LOWEST,
+    searchType: EType.USER,
+    searchValue: 'Kirian_',
+})
+```
+
+- Get top 25 items, of the 1st page, listed by seller A-Z, on a release
+
+```js
+import DiscogsMarketplace, { EType } from 'discogs-marketplace-api-nodejs'
+
+// https://www.discogs.com/sell/release/767931?sort=seller,asc&limit=25&page=1
+const result = await DiscogsMarketplace.search({
+    sort: ESort.SELLER_AZ,
+    searchType: EType.RELEASE,
+    searchValue: '767931',
+})
+```
+
+- Get top 100 items, of the 1st page, listed by newest, on a string search
+
+```js
+import DiscogsMarketplace, { EType } from 'discogs-marketplace-api-nodejs'
+
+// https://www.discogs.com/sell/list?sort=listed,desc&limit=100&q=in+flames&page=1
+const result = await DiscogsMarketplace.search({
+    limit: 100,
+    sort: ESort.LISTED_NEWEST,
+    searchType: EType.STRING,
+    searchValue: 'in flames',
+})
+```
+
+- Get top 25 items, of the 1st page, listed by newest, on a seller inventory
+
+```js
+import DiscogsMarketplace, { EType } from 'discogs-marketplace-api-nodejs'
+
+// https://www.discogs.com/seller/Kirian_/profile?sort=listed,desc&limit=25&page=1
+const result = await DiscogsMarketplace.search({
+    sort: ESort.LISTED_NEWEST,
+    searchType: EType.STRING,
+    searchValue: '',
+    seller: 'Kirian_',
+})
+```
+
+- Get top 25 items, of the 1st page, listed by newest, on a user wantlist, on a seller inventory
+
+```js
+import DiscogsMarketplace, { EType } from 'discogs-marketplace-api-nodejs'
+
+// https://www.discogs.com/seller/Kirian_/mywants?sort=listed,desc&limit=25&user=Kirian_&page=1
+const result = await DiscogsMarketplace.search({
+    sort: ESort.LISTED_NEWEST,
+    searchType: EType.USER,
+    searchValue: 'Kirian_',
+    seller: 'Kirian_',
+})
 ```
 
 ## Data format
 
-You can provide parameters to the function according to this interface:
+You can provide parameters to `DiscogsMarketplace.search` function according to this interface:
 
 ```ts
 interface IInput {
@@ -175,15 +245,14 @@ interface IItem {
         base: string
         shipping: string
     }
-    from: {
-        countryName: string
-        isoCountryName: ECountryName
-        isoCountryCode: ECountryCode
+    country: {
+        name: string
+        code: ECountryCode
     }
     community: {
         have: number
         want: number
-    }    
+    }
     release: {
         id: number
         url: string

diff --git a/src/interfaces/item.interface.ts b/src/interfaces/item.interface.ts
@@ -1,4 +1,4 @@
-import { ECountryCode, ECountryName } from 'enums/iso'
+import { ECountryCode } from 'enums/iso'
 
 /**
  * One item from discogs
@@ -67,13 +67,11 @@ export default interface IItem {
         shipping: string
     }
     /** From */
-    from: {
-        /** CountryName */
-        countryName: string
-        /** IsoCountryName */
-        isoCountryName: ECountryName
-        /** IsoCountryCode */
-        isoCountryCode: ECountryCode
+    country: {
+        /** Name */
+        name: string
+        /** Iso code */
+        code: ECountryCode
     }
     /** Community */
     community: {

diff --git a/src/marketplace.ts b/src/marketplace.ts
@@ -194,7 +194,7 @@ export default abstract class Marketplace {
                 const have = Number.parseInt(el.querySelector('.community_summary .community_result:nth-child(1) .community_number')?.textContent ?? '', 10)
                 const want = Number.parseInt(el.querySelector('.community_summary .community_result:nth-child(2) .community_number')?.textContent ?? '', 10)
                 const countryName = el.querySelector('.seller_info li:nth-child(3)')?.textContent?.split(':')?.[1] ?? ''
-                const isoCountryCode = (Object.keys(ECountryCode).find((key: string) => (ECountryName[key as ECountryCode] === countryName))
+                const countryCode = (Object.keys(ECountryCode).find((key: string) => (ECountryName[key as ECountryCode] === countryName))
                     || EDiscogsCountryNameToIsoCode[countryName as keyof typeof EDiscogsCountryNameToIsoCode]) as ECountryCode
                 const releaseId = Number.parseInt(
                     el.querySelector<HTMLLinkElement>('a.item_release_link')?.href.split('release/')?.pop()?.split('-')?.shift() ?? '0', 10,
@@ -249,10 +249,9 @@ export default abstract class Marketplace {
                         base: this.convertCurrency(el.querySelector('.price')?.textContent?.replace(/\s+/g, ' ')?.replace(/,/, '.') ?? ''),
                         shipping: Number.isNaN(parseFloat(shipping)) ? null : shipping,
                     },
-                    from: {
-                        countryName,
-                        isoCountryName: ECountryName[isoCountryCode] ?? '',
-                        isoCountryCode,
+                    country: {
+                        name: countryName,
+                        code: countryCode,
                     },
                     community: {
                         have: Number.isNaN(have) ? 0 : have,

diff --git a/test/app.test.ts b/test/app.test.ts
@@ -56,9 +56,8 @@ describe('Test marketplace.ts', () => {
         expect(res.items[0]?.seller?.score).not.toBe(null)
         expect(res.items[0]?.price?.base).not.toBe(null)
         expect(res.items[0]?.price?.shipping).not.toBe(null)
-        expect(res.items[0]?.from?.countryName).not.toBe(null)
-        expect(res.items[0]?.from?.isoCountryName).not.toBe(null)
-        expect(res.items[0]?.from?.isoCountryCode).not.toBe(null)
+        expect(res.items[0]?.country?.name).not.toBe(null)
+        expect(res.items[0]?.country?.code).not.toBe(null)
         expect(res.items[0]?.community?.have).not.toBe(null)
         expect(res.items[0]?.community?.want).not.toBe(null)
         expect(res.items[0]?.release.url).not.toBe(null)