mixcloud-fetch - npm Package Compare versions

Comparing version 0.1.1 to 1.0.0

package.json

 {
   "name": "mixcloud-fetch",
-  "version": "0.1.1",
-  "description": "JS library for fetching Mixcloud resources",
-  "main": "lib/index.js",
+  "version": "1.0.0",
+  "description": "Node module for fetching Mixcloud resources",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "build": "npm run prepare",
+    "build:esm": "npx tsc -p tsconfig-esm.json",
+    "build:cjs": "npx tsc -p tsconfig.json",
+    "prepare": "rm -rf dist && npm run build:esm && npm run build:cjs && bash fixup.sh",
+    "lint": "npx eslint ./src && npx eslint ./examples",
+    "lint:fix": "npx eslint ./src --fix && npx eslint ./examples --fix",
+    "doc": "npx typedoc",
+    "example": "func() { npx ts-node ./examples/${1}.ts; }; func"
   },
+  "main": "./dist/cjs/index-cjs.js",
+  "module": "./dist/mjs/index.js",
+  "types": "./dist/mjs/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/mjs/index.d.ts",
+        "default": "./dist/mjs/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index-cjs.js"
+      }
+    }
+  },
+  "author": "Patrick Kan <[e-mail]> (https://github.com/patrickkfkan)",
   "repository": {
@@ -13,2 +35,9 @@ "type": "git",
   },
+  "license": "MIT",
+  "directories": {
+    "dist": "./dist"
+  },
+  "engines": {
+    "node": ">=14"
+  },
   "keywords": [
@@ -23,4 +52,15 @@ "mixcloud",
   ],
-  "author": "Patrick Kan",
-  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^14.18.38",
+    "@types/node-fetch": "^2.6.4",
+    "@typescript-eslint/eslint-plugin": "^5.56.0",
+    "@typescript-eslint/parser": "^5.56.0",
+    "eslint": "^8.36.0",
+    "eslint-plugin-tsdoc": "^0.2.17",
+    "ts-node": "^10.9.1",
+    "typedoc": "^0.24.0",
+    "typedoc-plugin-markdown": "^3.14.0",
+    "typedoc-plugin-rename-defaults": "^0.6.4",
+    "typescript": "^4.9.5"
+  },
   "dependencies": {
@@ -30,4 +70,4 @@ "base64-min": "^2.0.0",
     "node-cache": "^5.1.2",
-    "node-fetch": "^2.6.1"
+    "node-fetch": "^2.6.9"
   }
 }

README.md

 # mixcloud-fetch
 
-A JS library for fetching Mixcloud resources.
+Node module for fetching Mixcloud resources.
 
-Note: this library does not support user logins, so you won't be able to fetch exclusive content or access account-specific features.
+Note: `mixcloud-fetch` does not support user login, so you won't be able to fetch exclusive content or access account-specific features.
 
@@ -16,28 +16,31 @@ # Installation
 ```
-const mcfetch = require('mixcloud-fetch');
+import mcfetch from 'mixcloud-fetch';
 
-mcfetch.tag(['ambient', 'lounge']).getShows().then( shows => {
-    ...
-});
+// Get shows matching the 'ambient' and 'lounge' tags
+const shows = await mcfetch.tag(['ambient', 'lounge']).getShows();
 
-mcfetch.search('jazz funk').getTags().then( tags => {
-    ...
-});
+// Search for tags matching 'jazz funk'
+const tags = await mcfetch.search('jazz funk').getTags();
 ```
 
-### Tag functions
+Here, `mcfetch` is the default [MixcloudFetch](docs/api/classes/MixcloudFetch.md) instance exported by `mixcloud-fetch`. The `MixcloudFetch` class defines methods for accessing the underlying APIs.
 
-A tag is used to discover shows and is identified by its **slug**. To access tag-related functions, you need to obtain a `Tag` object with the slug.
+## Tag API
 
+#### Access method
+
+#### `MixcloudFetch#tag(slug | slug[])`
+
+Returns a [TagAPI](docs/api/classes/TagAPI.md) instance targeting the tag given by `slug`, or multiple tags given by `slug[]`.
+
+#### Description
+
+A tag is used to discover shows and is identified by its **slug**. To access the Tag API, call the `tag()` method of a `MixcloudFetch` instance, passing into it the slug of the target tag.
+
 ```
 const slug = 'jazz';
 const tag = mcfetch.tag(slug);
-
-// Fetch shows matching the 'jazz' tag
-tag.getShows().then( shows => {
-    ...
-});
 ```
 
-You can encapsulate multiple tags in a `Tag` object by putting their slugs into an array:
+To target multiple tags, put their slugs into an array and pass the array into `tag()`:
 
@@ -50,128 +53,599 @@ ```
 const tag = mcfetch.tag(slugs);
-
-// Fetch shows matching both the 'jazz' and 'funk' tags
-tag.getShows().then( shows => {
-    ...
-});
 ```
 
-The following functions are provided by a `Tag` object. Each of these functions returns a Promise that resolves to the data requested.
+You can then call methods provided by `TagAPI`.
 
-| Function              | Resolves To                                 |                                                                                         |
-|-----------------------|-----------------------------------------------|-------------------------------------------------------------------------------------------|
-| getInfo()             | Information about the represented tag(s)      |[Example](examples/tag/getInfo.js) ([output](examples/tag/getInfo_output.txt))             |
-| getShows([params])*   | Cloudcasts matching the represented tag(s)    |[Example](examples/tag/getShows.js) ([output](examples/tag/getShows_output.txt))           |
-| getFeatured([params])*| Featured cloudcasts matching the represented tag(s)|[Example](examples/tag/getFeatured.js) ([output](examples/tag/getFeatured_output.txt))|
+#### API methods
 
-*`params` specify what to return in the results. Check the example for what params you can specify.
+<details>
+<summary><code>TagAPI#getInfo()</code></summary>
+<br />
 
-### User functions
+[Example](examples/tag/getInfo.ts) ➔ [Output](examples/tag/getInfo_output.txt)
 
-A user is identified by his or her **username**. To access user-related functions, you need to obtain a `User` object with the username.
+<p>Fetches information about the target tag(s).</p>
 
+**Returns**
+
+Promise:
+- If none of the target tag(s) exist, the Promise resolves to `null`.
+- Otherwise, the Promise resolves to an Array of [Tag](docs/api/interfaces/Tag.md) items. Only tags that exist will be included in the Array.
+
+---
+</details>
+
+<details>
+<summary><code>TagAPI#getShows([params])</code></summary>
+<br />
+
+[Example](examples/tag/getShows.ts) ➔ [Output](examples/tag/getShows_output.txt)
+
+<p>Fetches Cloudcasts matching the target tag(s).</p>
+
+**Params**
+
+`params`: (object) (*optional* and *all properties optional*)
+
+| Property      | Description               |
+|---------------|---------------------------|
+| `orderBy`     | (string) `trending` \| `popular` \| `latest`. Default: `trending`      |
+| `country`     | <p>(string) Country code - **only supported when `orderBy` is `trending`.**</p><p>If specified, return Cloudcasts originating from  `country`. For the list of values you can specify, call [MiscAPI#getCountries()](#api-methods-6).</p><p>If not specified, the default value will be determined by Mixcloud.</p> |
+| `limit`       | (number) Number of items to fetch (max: 100). Default: 20 |
+| `pageToken`   | (string) Continuation token for fetching the next batch of items following the previous fetch.
+
+**Returns**
+
+- If none of the target tag(s) exist, the Promise resolves to `null`.
+- Otherwise, the Promise resolves to an object with the following properties:
+
+| Property      | Description               |
+|---------------|---------------------------|
+| `items`       | (Array) The list of [Cloudcast](docs/api/interfaces/Cloudcast.md) items fetched.
+| `nextPageToken` | <p>(string) If available, the continuation token for retrieving the next batch of items. Otherwise, there are no further items available.</p><p>To fetch the next batch of items, pass the token as `params.pageToken` in the next call to this method.</p>
+| `selectedTags` | (Array) The [Tag](docs/api/interfaces/Tag.md) items representing the target tags. |
+| `params`      | (object) Sanitized version of `params` used to request data from Mixcloud. |
+
+---
+</details>
+
+<details>
+<summary><code>TagAPI#getFeatured([params])</code></summary>
+<br />
+
+[Example](examples/tag/getFeatured.ts) ➔ [Output](examples/tag/getFeatured_output.txt)
+
+<p>Fetches featured Cloudcasts matching the target tag(s).</p>
+
+**Params**
+
+`params`: (object) (*optional* and *all properties optional*)
+
+| Property      | Description               |
+|---------------|---------------------------|
+| `orderBy`     | (string) `popular` \| `latest`. Default: `latest`      |
+| `limit`       | (number) Number of items to fetch (max: 100). Default: 20 |
+| `pageToken`   | (string) Continuation token for fetching the next batch of items following the previous fetch.
+
+**Returns**
+
+Promise:
+- If none of the target tag(s) exist, the Promise resolves to `null`.
+- Otherwise, the Promise resolves to an object with the following properties:
+
+| Property      | Description               |
+|---------------|---------------------------|
+| `items`       | (Array) The list of [Cloudcast](docs/api/interfaces/Cloudcast.md) items fetched.
+| `nextPageToken` | <p>(string) If available, the continuation token for retrieving the next batch of items. Otherwise, there are no further items available.</p><p>To fetch the next batch of items, pass the token as `params.pageToken` in the next call to this method.</p>
+| `selectedTags` | (Array) The [Tag](docs/api/interfaces/Tag.md) items representing the target tags. |
+| `params`      | (object) Sanitized version of `params` used to request data from Mixcloud. |
+
+---
+</details>
+
+## User API
+
+#### Access method
+
+#### `MixcloudFetch#user(username)`
+
+Returns a [UserAPI](docs/api/classes/UserAPI.md) instance targeting the user given by `username`.
+
+#### Description
+
+A user is identified by **username**. To access the User API, call the `user()` method of a `MixcloudFetch` instance, passing into it the username of the target user:
+
 ```
 const username = 'jazzcat';
 const user = mcfetch.user(username);
-
-// Fetch shows uploaded by the user
-user.getShows().then( shows => {
-    ...
-});
 ```
 
-The following functions are provided by a `User` object. Each of these functions returns a Promise that resolves to the data requested.
+You can then call methods provided by `UserAPI`.
 
-| Function              | Resolves To                                 |                                                                                           |
-|-----------------------|-----------------------------------------------|-------------------------------------------------------------------------------------------|
-| getInfo()             | Information about the user                    |[Example](examples/user/getInfo.js) ([output](examples/user/getInfo_output.txt))           |
-| getShows([params])*   | Cloudcasts uploaded by the user               |[Example](examples/user/getShows.js) ([output](examples/user/getShows_output.txt))         |
-| getPlaylists()        | Playlists owned by the user                   |[Example](examples/user/getPlaylists.js) ([output](examples/user/getPlaylists_output.txt)) |
+#### API methods
 
-*`params` specify what to return in the results. Check the example for what params you can specify.
+<details>
+<summary><code>UserAPI#getInfo()</code></summary>
+<br />
 
-### Playlist functions
+[Example](examples/user/getInfo.ts) ➔ [Output](examples/user/getInfo_output.txt)
 
-A playlist is identified by its ID. To access playlist-related functions, you need to obtain a `Playlist` object with the playlist's ID.
+<p>Fetches information about the target user.</p>
 
+**Returns**
+
+Promise resolving to [User](docs/api/interfaces/User.md), or `null` if target user does not exist.
+
+---
+</details>
+
+<details>
+<summary><code>UserAPI#getShows([params])</code></summary>
+<br />
+
+[Example](examples/user/getShows.ts) ➔ [Output](examples/user/getShows_output.txt)
+
+<p>Fetches Cloudcasts uploaded by the target user.</p>
+
+**Params**
+
+`params`: (object) (*optional* and *all properties optional*)
+
+| Property      | Description               |
+|---------------|---------------------------|
+| `orderBy`     | (string) 'trending' \| 'popular' \| 'latest' \| 'oldest'. Default: `latest`      |
+| `limit`       | (number) Number of items to fetch (max: 100). Default: 20 |
+| `pageToken`   | (string) Continuation token for fetching the next batch of items following the previous fetch.
+
+**Returns**
+
+Promise:
+- If target user does not exist, the Promise resolves to `null`.
+- Otherwise, the Promise resolves to an object with the following properties:
+
+| Property      | Description               |
+|---------------|---------------------------|
+| `items`       | (Array) The list of [Cloudcast](docs/api/interfaces/Cloudcast.md) items fetched.
+| `nextPageToken` | <p>(string) If available, the continuation token for retrieving the next batch of items. Otherwise, there are no further items available.</p><p>To fetch the next batch of items, pass the token as `params.pageToken` in the next call to this method.</p>
+| `params`      | (object) Sanitized version of `params` used to request data from Mixcloud. |
+
+---
+</details>
+
+<details>
+<summary><code>UserAPI#getPlaylists()</code></summary>
+<br />
+
+[Example](examples/user/getPlaylists.ts) ➔ [Output](examples/user/getPlaylists_output.txt)
+
+<p>Fetches playlists owned by the target user.</p>
+
+**Returns**
+
+Promise:
+- If target user does not exist, the Promise resolves to `null`.
+- Otherwise, the Promise resolves to an Array of [Playlist](docs/api/interfaces/Playlist.md) items.
+
+---
+</details>
+
+<details>
+<summary><code>UserAPI#getLiveStream()</code></summary>
+<br />
+
+[Example](examples/user/getLiveStream.ts) ➔ [Output](examples/user/getLiveStream_output.txt)
+
+<p>Fetches the target user's live stream.</p>
+
+> Note: it is possible that the live stream has ended. Check the `status` property to ascertain.
+
+**Returns**
+
+Promise:
+- If there is no live stream, or target user does not exist, the Promise resolves to `null`.
+- Otherwise, the Promise resolves to a [LiveStream](docs/api/interfaces/LiveStream.md) item.
+
+---
+</details>
+
+## Playlist API
+
+#### Access method
+
+#### `MixcloudFetch#playlist(playlistID)`
+
+Returns a [PlaylistAPI](docs/api/classes/PlaylistAPI.md) instance targeting the playlist given by `playlistID`.
+
+#### Description
+
+A playlist is identified by its ID. To access the Playlist API, call the `playlist()` method of a `MixcloudFetch` instance, passing into it the ID of the target playlist:
+
 ```
 const playlistId = 'UGxheWxpc3Q6MTM5NDM2MA==';
 const playlist = mcfetch.playlist(playlistId);
-
-// Fetch shows in the playlist
-playlist.getShows().then( shows => {
-    ...
-});
 ```
 
-The following functions are provided by a `Playlist` object. Each of these functions returns a Promise that resolves to the data requested.
+You can then call methods provided by `PlaylistAPI`.
 
-| Function              | Resolves To                                 |                                                                                           |
-|-----------------------|-----------------------------------------------|-------------------------------------------------------------------------------------------|
-| getInfo()             | Information about the playlist                |[Example](examples/playlist/getInfo.js) ([output](examples/playlist/getInfo_output.txt))   |
-| getShows([params])*   | Cloudcasts in the playlist                    |[Example](examples/playlist/getShows.js) ([output](examples/playlist/getShows_output.txt)) |
+#### API methods
 
-*`params` specify what to return in the results. Check the example for what params you can specify.
+<details>
+<summary><code>PlaylistAPI#getInfo()</code></summary>
+<br />
 
-### Cloudcast functions
+[Example](examples/playlist/getInfo.ts) ➔ [Output](examples/playlist/getInfo_output.txt)
 
-A cloudcast is identified by its ID. To access cloudcast-related functions, you need to obtain a `Cloudcast` object with the cloudcast's ID.
+<p>Fetches information about the target playlist.</p>
 
+**Returns**
+
+Promise resolving to [Playlist](docs/api/interfaces/Playlist.md), or `null` if target playlist does not exist.
+
+---
+</details>
+
+<details>
+<summary><code>PlaylistAPI#getShows([params])</code></summary>
+<br />
+
+[Example](examples/playlist/getShows.ts) ➔ [Output](examples/playlist/getShows_output.txt)
+
+<p>Fetches Cloudcasts in the target playlist.</p>
+
+**Params**
+
+`params`: (object) (*optional* and *all properties optional*)
+
+| Property      | Description               |
+|---------------|---------------------------|
+| `limit`       | (number) Number of items to fetch (max: 100). Default: 20 |
+| `pageToken`   | (string) Continuation token for fetching the next batch of items following the previous fetch.
+
+**Returns**
+
+Promise:
+- If target playlist does not exist, the Promise resolves to `null`.
+- Otherwise, the Promise resolves to an object with the following properties:
+
+| Property      | Description               |
+|---------------|---------------------------|
+| `items`       | (Array) The list of [Cloudcast](docs/api/interfaces/Cloudcast.md) items fetched.
+| `nextPageToken` | <p>(string) If available, the continuation token for retrieving the next batch of items. Otherwise, there are no further items available.</p><p>To fetch the next batch of items, pass the token as `params.pageToken` in the next call to this method.</p>
+
+---
+</details>
+
+## Cloudcast API
+
+#### Access method
+
+#### `MixcloudFetch#cloudcast(cloudcastID)`
+
+Returns a [CloudcastAPI](docs/api/classes/CloudcastAPI.md) instance targeting the Cloudcast given by `cloudcastID`.
+
+#### Description
+
+A Cloudcast is identified by its ID. To access the Cloudcast API, call the `cloudcast()` method of a `MixcloudFetch` instance, passing into it the ID of the target Cloudcast:
+
 ```
 const cloudcastId = 'Q2xvdWRjYXN0OjE1MDg0MzQzNA==';
 const cloudcast = mcfetch.cloudcast(cloudcastId);
-
-// Fetch info about the cloudcast
-cloudcast.getInfo().then( info => {
-    ...
-});
 ```
 
-There is only one function provided by a `Cloudcast` object:
+You can then call methods provided by `CloudcastAPI`.
 
-| Function              | Resolves To                                 |                                                                                           |
-|-----------------------|-----------------------------------------------|-------------------------------------------------------------------------------------------|
-| getInfo()             | Information about the cloudcast               |[Example](examples/cloudcast/getInfo.js) ([output](examples/cloudcast/getInfo_output.txt)) |
+#### API methods
 
-### Search functions
+<details>
+<summary><code>CloudcastAPI#getInfo()</code></summary>
+<br />
 
-The library supports searching Tags, Shows and Users. To access the search functions, you need to obtain a `Search` object with the keywords to search for.
+[Example](examples/cloudcast/getInfo.ts) ➔ [Output](examples/cloudcast/getInfo_output.txt)
 
+<p>Fetches information about the target Cloudcast.</p>
+
+**Returns**
+
+Promise resolving to [Cloudcast](docs/api/interfaces/Cloudcast.md), or `null` if target Cloudcast does not exist.
+
+---
+</details>
+
+## Search API
+
+#### Access method
+
+#### `MixcloudFetch#search(keywords)`
+
+Returns a [SearchAPI](docs/api/classes/SearchAPI.md) instance targeting the `keywords` to search for.
+
+#### Description
+
+`mixcloud-fetch` supports searching Tags, Shows and Users. To access the Search API, call the `search()` method of a `MixcloudFetch` instance, passing into it the keywords you would like to search for.
+
 ```
 const keywords = 'ambient lounge';
 const search = mcfetch.search(keywords);
+```
 
-// Fetch shows matching 'ambient lounge':
-search.getShows().then( shows => {
+You can then call methods provided by `SearchAPI`.
+
+#### API methods
+
+<details>
+<summary><code>SearchAPI#getTags([params])</code></summary>
+<br />
+
+[Example](examples/search/getTags.ts) ➔ [Output](examples/search/getTags_output.txt)
+
+<p>Searches for tags matching the target keywords.</p>
+
+**Params**
+
+`params`: (object) (*optional* and *all properties optional*)
+
+| Property      | Description               |
+|---------------|---------------------------|
+| `limit`       | (number) Number of items to fetch (max: 100). Default: 20 |
+| `pageToken`   | (string) Continuation token for fetching the next batch of items following the previous fetch.
+
+**Returns**
+
+Promise resolving to an object with the following properties:
+
+| Property      | Description               |
+|---------------|---------------------------|
+| `items`       | (Array) The list of [Tag](docs/api/interfaces/Tag.md) items found.
+| `nextPageToken` | <p>(string) If available, the continuation token for retrieving the next batch of items. Otherwise, there are no further items available.</p><p>To fetch the next batch of items, pass the token as `params.pageToken` in the next call to this method.</p>
+| `params`      | (object) Sanitized version of `params` used to request data from Mixcloud. |
+
+---
+</details>
+
+<details>
+<summary><code>SearchAPI#getShows([params])</code></summary>
+<br />
+
+[Example](examples/search/getShows.ts) ➔ [Output](examples/search/getShows_output.txt)
+
+<p>Searches for Cloudcasts matching the target keywords.</p>
+
+**Params**
+
+`params`: (object) (*optional* and *all properties optional*)
+
+| Property      | Description               |
+|---------------|---------------------------|
+| `dateUploaded`| (string) `pastWeek` \| `pastMonth` \| `pastYear` \| `anyTime`. Default: `anyTime` |
+| `requireTimeStamp` | (boolean) If `true`, only return Cloudcasts that are timestamped. Default: `false` |
+| `limit`       | (number) Number of items to fetch (max: 100). Default: 20 |
+| `pageToken`   | (string) Continuation token for fetching the next batch of items following the previous fetch.
+
+**Returns**
+
+Promise resolving to an object with the following properties:
+
+| Property      | Description               |
+|---------------|---------------------------|
+| `items`       | (Array) The list of [Cloudcast](docs/api/interfaces/Cloudcast.md) items found.
+| `nextPageToken` | <p>(string) If available, the continuation token for retrieving the next batch of items. Otherwise, there are no further items available.</p><p>To fetch the next batch of items, pass the token as `params.pageToken` in the next call to this method.</p>
+| `params`      | (object) Sanitized version of `params` used to request data from Mixcloud. |
+
+---
+</details>
+
+<details>
+<summary><code>SearchAPI#getUsers([params])</code></summary>
+<br />
+
+[Example](examples/search/getUsers.ts) ➔ [Output](examples/search/getUsers_output.txt)
+
+<p>Searches for users matching the target keywords.</p>
+
+**Params**
+
+`params`: (object) (*optional* and *all properties optional*)
+
+| Property      | Description               |
+|---------------|---------------------------|
+| `dateJoined`| (string) `pastWeek` \| `pastMonth` \| `pastYear` \| `anyTime`. Default: `anyTime` |
+| `userType`    | (string) `uploader` \| `listener` \| `any`. Default: `any`
+| `limit`       | (number) Number of items to fetch (max: 100). Default: 20 |
+| `pageToken`   | (string) Continuation token for fetching the next batch of items following the previous fetch.
+
+**Returns**
+
+Promise resolving to an object with the following properties:
+
+| Property      | Description               |
+|---------------|---------------------------|
+| `items`       | (Array) The list of [User](docs/api/interfaces/User.md) items found.
+| `nextPageToken` | <p>(string) If available, the continuation token for retrieving the next batch of items. Otherwise, there are no further items available.</p><p>To fetch the next batch of items, pass the token as `params.pageToken` in the next call to this method.</p>
+| `params`      | (object) Sanitized version of `params` used to request data from Mixcloud. |
+
+---
+</details>
+
+## LiveStream API
+
+#### Access property
+
+#### `MixcloudFetch#liveStream`
+
+Returns a [LiveStreamAPI](docs/api/classes/LiveStreamAPI.md) isntance.
+
+#### Description
+
+The LiveStream API allows you to fetch Mixcloud live streams.
+
+#### API methods
+
+> For fetching the live stream of a user, call [UserAPI#getLiveStream()](#api-methods-1) instead.
+
+<details>
+<summary><code>LiveStreamAPI#getCurrent([params])</code></summary>
+<br />
+
+[Example](examples/live_stream/getCurrent.ts) ➔ [Output](examples/live_stream/getCurrent_output.txt)
+
+<p>Fetches the current live streams on Mixcloud.</p>
+
+**Params**
+
+`params`: (object) (*optional* and *all properties optional*)
+
+| Property      | Description               |
+|---------------|---------------------------|
+| `orderBy`     | (string) `popular` \| `mostRecent`. Default: `popular` |
+| `category`    | <p>(string) If specified, return live streams in  `category`.</p><p>For the list of values you can specify, call `getCategories()` of this API.</p> |
+| `limit`       | (number) Number of items to fetch (max: 100). Default: 20 |
+| `pageToken`   | (string) Continuation token for fetching the next batch of items following the previous fetch.
+
+**Returns**
+
+Promise resolving to an object with the following properties:
+
+| Property      | Description               |
+|---------------|---------------------------|
+| `items`       | (Array) The list of [LiveStream](docs/api/interfaces/LiveStream.md) items fetched.
+| `nextPageToken` | <p>(string) If available, the continuation token for retrieving the next batch of items. Otherwise, there are no further items available.</p><p>To fetch the next batch of items, pass the token as `params.pageToken` in the next call to this method.</p>
+| `params`      | (object) Sanitized version of `params` used to request data from Mixcloud. |
+
+---
+</details>
+
+<details>
+<summary><code>LiveStreamAPI#getCategories()</code></summary>
+<br />
+
+[Example](examples/live_stream/getCategories.ts) ➔ [Output](examples/live_stream/getCategories_output.txt)
+
+<p>Fetches the available live stream categories.</p>
+
+**Returns**
+
+Promise resolving to an Array of strings. Each array element is the name of a live stream category.
+
+---
+</details>
+
+## Miscellaneous API
+
+#### Access property
+
+#### `MixcloudFetch#misc`
+
+Returns a [MiscAPI](docs/api/classes/MiscAPI.md) instance.
+
+#### Description
+
+The Miscellaneous API provides methods for obtaining values that can be used in other API methods.
+
+#### API methods
+
+<details>
+<summary><code>MiscAPI#getCategories()</code></summary>
+<br />
+
+[Example](examples/misc/getCategories.ts) ➔ [Output](examples/misc/getCategories_output.txt)
+
+Fetches the list of Mixcloud categories. See Usage below for example of fetching Cloudcasts belonging to a specific category.
+
+**Returns**
+
+Promise resolving to a [CategoryBundle](docs/api/interfaces/Category.md). A bundle is an object with the following structure:
+
+```
+{
+  bundle1: Category[],
+  bundle2: Category[]
+}
+```
+
+A [Category](docs/api/interfaces/Category.md) is an object wih the following key properties:
+
+| Property          | Description                    |
+|-------------------|--------------------------------|
+| `name`            | (string) Category name         |
+| `slug`            | (string) Category identifier   |
+
+**Usage**
+
+Say we have the following category bundle obtained from `getCategories()`:
+
+```
+{
+  music: [
+    { name: 'Ambient', slug: 'ambient' },
+    { name: 'Bass', slug: 'bass' }
     ...
-});
+  ],
+  talk: [
+    { name: 'Business', slug: 'business' },
+    { name: 'Comedy', slug: 'comedy' }
+    ...
+  ]
+}
 ```
 
-The following functions are provided by a `Search` object. Each of these functions returns a Promise that resolves to the data requested.
+To obtain Cloudcasts belonging to the 'Ambient' category, use its `slug` property in conjunction with the Tag API:
 
-| Function              | Resolves To                                 |                                                                                           |
-|-----------------------|-----------------------------------------------|-------------------------------------------------------------------------------------------|
-| getTags([params])     | Tags matching the given keywords              |[Example](examples/search/getTags.js) ([output](examples/search/getTags_output.txt))       |
-| getShows([params])    | Cloudcasts matching the given keywords        |[Example](examples/search/getShows.js) ([output](examples/search/getShows_output.txt))     |
-| getUsers([params])    | Users matching the given keywords             |[Example](examples/search/getUsers.js) ([output](examples/search/getUsers_output.txt))     |
+```
+const tag = mcfetch.tag(bundle['music'][0]['slug']); 
+const showsInAmbientCategory = await tag.getShows(); 
+```
 
-`params` specify what to return in the results. Check the example for what params you can specify.
+---
+</details>
 
-### Miscellaneous functions
+<details>
+<summary><code>MiscAPI#getCountries()</code></summary>
+<br />
 
+[Example](examples/misc/getCountries.ts) ➔ [Output](examples/misc/getCountries_output.txt)
+
+Fetches the list of countries available on Mixcloud. See Usage below for example of fetching Cloudcasts originating from a specific country.
+
+**Returns**
+
+Promise resolving to a [CountryBundle](docs/api/interfaces/CountryBundle.md). A bundle is an object with the following properties:
+
+| Property          | Description                    |
+|-------------------|--------------------------------|
+| `default`         | (object) The default country   |
+| `available`       | (Array) The list of available countries |
+
+Each [Country](docs/api/interfaces/Country.md) is an object with the following properties:
+
+| Property          | Description                    |
+|-------------------|--------------------------------|
+| `code`            | (string) Country code          |
+| `name`            | (string) Country name          |
+
+**Usage**
+
+Say we have the following countries returned by `getCountries()`:
+
 ```
-// Get Mixcloud categories
-mcfetch.misc.getCategories().then( categories => {
+{
+  default: { code: 'HKG', name: 'Hong Kong' },
+  available: [
+    { code: 'GLOBAL', name: 'Global' },
+    { code: 'AUS', name: 'Australia' },
+    { code: 'CAN', name: 'Canada' },
     ...
-});
+  ]
+}
+```
 
-// Get the list of available countries as well as the default
-mcfetch.misc.getCountries().then( countries => {
-    ...
+To obtain Cloudcasts matching the 'jazz' tag and originating from Canada:
+
+```
+const tag = mcfetch.tag('jazz'); 
+const jazzShowsFromCanada = await tag.getShows({
+  country: 'CAN' // Use the country code
 });
 ```
 
-| Function              | Resolves To                                 |                                                                                           |
-|-----------------------|-----------------------------------------------|-------------------------------------------------------------------------------------------|
-| getCategories()       | Mixcloud categories                           |[Example](examples/misc/getCategories.js) ([output](examples/misc/getCategories_output.txt)) |
-| getCountries()        | Available countries and the default           |[Example](examples/misc/getCountries.js) ([output](examples/misc/getCountries_output.txt)) |
+---
+</details>
 
@@ -222,2 +696,6 @@ # Rate Limiting
 
+1.0.0
+- Migrate to Typescript; package as ESM + CJS hybrid module
+- Add support for fetching live streams
+
 0.1.1:
@@ -224,0 +702,0 @@ - Fix fetch errors due to Mixcloud changing their GraphQL URL.

New alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Fixed alerts

Dynamic require

Supply chain risk

Dynamic require can indicate the package is performing dangerous or unsafe dynamic code execution.

Found 1 instance in 1 package

No tests

Quality

Package does not have any tests. This is a strong signal of a poorly maintained or low quality package.

Found 1 instance in 1 package

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

Found 1 instance in 1 package

Improved metrics

Number of package files

304

496.08%

Lines of code

5800

210.16%

Number of low quality alerts

1

-66.67%

Number of lines in readme file

703

212.44%

Number of low supply chain risk alerts

0

-100%

Worsened metrics

Total package byte prevSize

536204

-67.75%

Dev dependency count

11

Infinity%

Dependency changes

• Updated

  node-fetch@^2.6.9