\n\n# bandcamp-fetch\n\nLibrary for scraping Bandcamp content.\n\nCoverage:\n\n- Bandcamp Discover\n- Album and track info\n- Artists, labels, label artists, discography\n- Articles (aka. Bandcamp Daily)\n- Shows\n- Tags, including releases and highlights by tag\n- Search\n- Fan collections, wishlists and following artists / genres\n\nPackaged as ESM + CJS hybrid module with typings.\n\n# Installation\n\n```bash\nnpm i --save bandcamp-fetch\n```\n\n### Optional packages\n\nThe above command will install the following optional packages:\n\n```\npuppeteer puppeteer-extra puppeteer-extra-plugin-stealth\n```\n\nThese packages enable automated cookie fetching, which is performed when utilizing [search functions](#search-api) without [setting a cookie](#user-sessions).\n\nYou can skip the installation of these optional packages:\n\n```bash\nnpm i --save --omit=optional bandcamp-fetch\n```\n\nBe aware that, without at least the `puppeteer` package, performing searches without a cookie will result in an error.\n\n**Setting Puppeteer's executable path**\n\nWhen you install `puppeteer`, the process will automatically download a suitable browser executable to use at runtime. In case you want `puppeteer` to use your own browser executable, you can do so as follows:\n\n```javascript\nimport bcfetch from 'bandcamp-fetch';\n\nbcfetch.setPuppeteerExecutablePath('/path/to/executable');\n```\n\n# Usage\n\n```javascript\nimport bcfetch from 'bandcamp-fetch';\n\nconst results = await bcfetch.discovery.discover(...);\n```\n\n### User Sessions\n\nWhen you visit Bandcamp, a \"Cookie\" is used to identify the user session. If you are signed in, you can pass the value of this cookie to the library and gain access to your private collection as well as high-quality MP3 streams of purchased media:\n\n```javascript\nbcfetch.setCookie('xxxx');\n\nconst album = await bcfetch.album.getInfo({\n albumUrl: '...' // URL of purchased album\n});\n\n// Normal quality stream\nconst streamUrl = album.tracks[0].streamUrl;\n\n// High quality stream - only available when `cookie` is set\nconst streamUrlHQ = album.tracks[0].streamUrlHQ;\n```\n\nGuide: [How to obtain Cookie](https://github.com/patrickkfkan/bandcamp-fetch/wiki/How-to-obtain-Cookie)\n\n### `BandcampFetch`\n\nThe library exports a default [BandcampFetch](./docs/api/classes/BandcampFetch.md) instance mainly for backward compatibility with previous versions:\n\n```javascript\n// Imports the default `BandcampFetch` instance\nimport bcfetch from 'bandcamp-fetch';\n```\n\nYou can also create separate instances. This is useful when you want to support multiple user sessions:\n\n```javascript\nimport { BandcampFetch } from 'bandcamp-fetch';\n\nconst bcfetch1 = new BandcampFetch({\n cookie: 'xxxx' // Cookie for user session 1\n});\n\nconst bcfetch2 = new BandcampFetch();\nbcfetch2.setCookie('yyyy'); // Cookie for user sesion 2\n```\n\n### \n\n# API\n\n## Discovery API\n\nTo access the Discovery API:\n\n```javascript\nimport bcfetch from 'bandcamp-fetch';\n\nconst discovery = bcfetch.discovery;\n\nconst options = await discovery.getAvailableOptions();\nconst results = await discovery.discover(...);\n```\n**Methods:**\ndiscover([params])Fetches items through Bandcamp Discover.
\n\n**Params**\n\n- `params`: ([DiscoverParams](docs/api/interfaces/DiscoverParams.md)) (*optional* and *all properties optional*)\n - `genre`: (string)\n - `subgenre`: (string) only valid when `genre` is set to something other than 'all'.\n - `location`: (string)\n - `sortBy`: (string)\n - `category`: (number)\n - `time`: (number)\n - `customTags`: (Array<string>)\n - `size`: number\n - `albumImageFormat`: (string | number | [ImageFormat](docs/api/interfaces/ImageFormat.md))\n - `artistImageFormat`: (string | number | [ImageFormat](docs/api/interfaces/ImageFormat.md))\n - `merchImageFormat`: (string | number | [ImageFormat](docs/api/interfaces/ImageFormat.md))\n\nTo see what values can be set in `params`, call `getAvailableOptions()`.\n\n**Returns**\n\nPromise resolving to [DiscoverResult](docs/api/interfaces/DiscoverResult.md).\n\n**Continuation**\n\nCheck the `continuation` property of the returned result to see if more results are available. To obtain the next set of results, pass the value of `continuation` to `discover()`:\n\n```javascript\nconst results = await discovery.discover(...);\n\n// More results\nif (results.continuation) {\n const moreResults = await discovery.discover(results.continuation);\n ...\n}\n```\n\n---\ngetAvailableOptions()Fetches Bandcamp Discover options that can be used to configure params for passing into discover().
sanitizeDiscoverParams([params])Sanitizes params by setting default values for omitted properties and removing irrelevant or inapplicable ones.
\nNote that you don't have to call this method on params passed into discover() as they will be sanitized automatically.\n
getRecommendedTagsAndLocations()Fetches a list of tags and locations.
\n\n**Returns**\n\nPromise resolving to [TagsAndLocations](docs/api/interfaces/TagsAndLocations.md), which groups results into `tags` and `locations`.\n\n---\ngetFormats([filter])Fetches the list of image formats used in Bandcamp.
\n\n**Params**\n\n- `filter`: ([ImageFormatFilter](docs/api/enums/ImageFormatFilter.md)) (*optional*) if specified, narrows down the result to include only formats applicable to the specified value.\n\n**Returns**\n\nPromise resolving to Array<[ImageFormat](docs/api/interfaces/ImageFormat.md)>.\n\n---\ngetImageFormat(target, [fallbackId])Fetches the image format that matches target. If none is found, the result will be null.
getInfo(params)Fetches information about an artist or label.
\n\n**Params**\n\n- `params`: ([BandAPIGetInfoParams](docs/api/interfaces/BandAPIGetInfoParams.md))\n - `bandUrl`: (string)\n - `imageFormat`: (string | number | [ImageFormat](docs/api/interfaces/ImageFormat.md)) (*optional*)\n - `labelId`: (number) (*optional*)\n\nThe method tries to assemble the most complete set of data by scraping the following pages (returning immediately at any point the data becomes complete):\n\n1. The page referred to by `bandUrl`\n2. The 'music' page of the artist or label (`bandUrl/music`)\n3. The first album or track in the artist's or label's discography\n\nSometimes, label information is missing for artists even when they do belong to a label. If you know the `labelId` of the label that the artist belongs to, you can specify it in `params`. This will ensure that `label` will not be `null` in the artist info. If you pass a label URL to this function, you can find the `labelId` in the result.\n\n**Returns**\n\nPromise resolving to [Artist](docs/api/interfaces/Artist.md) or [Label](docs/api/interfaces/Label.md).\n\n---\ngetLabelArtists(params)Fetches the list of artists belonging to a label.
\n\n**Params**\n\n- `params`: ([BandAPIGetLabelArtistsParams](docs/api/interfaces/BandAPIGetLabelArtistsParams.md))\n - `labelUrl`: (string)\n - `imageFormat`: (string | number | [ImageFormat](docs/api/interfaces/ImageFormat.md)) (*optional*)\n\n**Returns**\n\nPromise resolving to Array<[LabelArtist](docs/api/README.md#labelartist)>.\n\n---\ngetDiscography(params)Fetches the list of albums and standalone tracks belonging to an artist or label.
\n\n**Params**\n\n- `params`: ([BandAPIGetDiscographyParams](docs/api/interfaces/BandAPIGetDiscographyParams.md))\n - `bandUrl`: (string)\n - `imageFormat`: (string | number | [ImageFormat](docs/api/interfaces/ImageFormat.md)) (*optional*)\n\n**Returns**\n\nPromise resolving to Array<[Album](docs/api/interfaces/Album.md) | [Track](docs/api/interfaces/Track.md)>.\n\n---\ngetInfo(params)Fetches info about an album.
\n\n**Params**\n\n- `params`: ([AlbumAPIGetInfoParams](docs/api/interfaces/AlbumAPIGetInfoParams.md))\n - `albumUrl`: (string)\n - `albumImageFormat`: (string | number | [ImageFormat](docs/api/interfaces/ImageFormat.md)) (*optional*)\n - `artistImageFormat`: (string | number | [ImageFormat](docs/api/interfaces/ImageFormat.md)) (*optional*)\n - `includeRawData`: (boolean) (*optional)\n\n**Returns**\n\nPromise resolving to [Album](docs/api/interfaces/Album.md).\n\n> If artist URL is not found in the scraped data, then `artist.url` will be set to the same value as `publisher.url`\n\n---\ngetInfo(params)Fetches info about a track.
\n\n**Params**\n\n- `params`: ([TrackAPIGetInfoParams](docs/api/interfaces/Tra))\n - `trackUrl`: (string)\n - `albumImageFormat`: (string | number | [ImageFormat](docs/api/interfaces/ImageFormat.md)) (*optional*)\n - `artistImageFormat`: (string | number | [ImageFormat](docs/api/interfaces/ImageFormat.md)) (*optional*)\n - `includeRawData`: (boolean) (*optional)\n\n**Returns**\n\nPromise resolving to [Track](docs/api/interfaces/Track.md).\n\n> If artist URL is not found in the scraped data, then `artist.url` will be set to the same value as `publisher.url`\n\n---\ngetRelated(params)Fetches the related tags for each value in `tags`, as well as the combined result.
\n\n**Returns**\n\nPromise resolving to [RelatedTags](docs/api/interfaces/RelatedTags.md), which has the following properties:\n- `single`: list of related tags for each tag queried\n- `combo`: the combined result of all the related tags\n\n---\nlist(params)Fetches the full list of Bandcamp shows.
\n\nEach list entry contains basic info about a show. To obtain full details, pass its `url` to `getShow()`.\n\n**Params**\n\n- `params`: ([ShowAPIListParams](docs/api/interfaces/ShowAPIListParams.md)) (*optional*)\n - `imageFormat`: (string | number | [ImageFormat](docs/api/interfaces/ImageFormat.md)) (*optional*)\n\n**Returns**\n\nPromise resolving to Array<[Show](docs/api/interfaces/Show.md)>.\n\n---\ngetShow(params)Fetches full details about the Bandcamp show referred to by params.showUrl.
getCategories()Fetches the list of Bandcamp Daily article categories. Categories are grouped into sections.
\n\n**Returns**\n\nPromise resolving to Array<[ArticleCategorySection](docs/api/interfaces/ArticleCategorySection.md)>.\n\n---\nlist(params)Fetches the list of Bandcamp Daily articles under the category specified by params.categoryUrl (or all categories if not specified).
getArticle(params)Fetches the contents of the Bandcamp Daily article at params.articleUrl.
getInfo(params)Fetches info about a fan.
\n\n**Params**\n\n- `params`: ([FanAPIGetInfoParams](docs/api/interfaces/FanAPIGetInfoParams.md)) (*optional*)\n - `username`: (string) (*optional*)\n - `imageFormat`: (string | number | [ImageFormat](docs/api/interfaces/ImageFormat.md)) (*optional*)\n\n If `username` is not specified, result will be obtained for the user of the [session](#user-sessions) tied to the `BandcampFetch` instance.\n\n**Returns**\n\nPromise resolving to [Fan](docs/api/interfaces/Fan.md).\n\n---\ngetCollection(params)Fetches the list of albums and tracks in a fan's collection.
\n\n**Params**\n\n- `params`: ([FanAPIGetItemsParams](docs/api/interfaces/FanAPIGetItemsParams.md))\n - `target`: (string | [FanItemsContinuation](docs/api/interfaces/FanItemsContinuation.md)) (*optional*) if username (string) is specified, returns the first batch of items in the collection. To obtain further items, call the method again but, instead of username, pass `continuation` from the result of the first call. If there are no further items available, `continuation` will be `null`.\n - `imageFormat`: (string | number | [ImageFormat](docs/api/interfaces/ImageFormat.md)) (*optional*)\n\nIf `target` is not specified, result will be obtained for the user of the [session](#user-sessions) tied to the `BandcampFetch` instance.\n\n**Returns**\n\nPromise resolving to ([FanPageItemsResult](docs/api/interfaces/FanPageItemsResult.md) | [FanContinuationItemsResult](docs/api/interfaces/FanContinuationItemsResult.md))<[Album](docs/api/interfaces/Album.md) | [Track](docs/api/interfaces/Track.md)>.\n\n---\ngetWishlist(params)Fetches the list of albums and tracks added to a fan's wishlist.
\n\n**Params**\n\n- `params`: ([FanAPIGetItemsParams](docs/api/interfaces/FanAPIGetItemsParams.md))\n - `target`: (string | [FanItemsContinuation](docs/api/interfaces/FanItemsContinuation.md)) (*optional*) if username (string) is specified, returns the first batch of items in the wishlist. To obtain further items, call the method again but, instead of username, pass `continuation` from the result of the first call. If there are no further items available, `continuation` will be `null`.\n - `imageFormat`: (string | number | [ImageFormat](docs/api/interfaces/ImageFormat.md)) (*optional*)\n\nIf `target` is not specified, result will be obtained for the user of the [session](#user-sessions) tied to the `BandcampFetch` instance.\n\n**Returns**\n\nPromise resolving to ([FanPageItemsResult](docs/api/interfaces/FanPageItemsResult.md) | [FanContinuationItemsResult](docs/api/interfaces/FanContinuationItemsResult.md))<[Album](docs/api/interfaces/Album.md) | [Track](docs/api/interfaces/Track.md)>.\n\n---\ngetFollowingArtistsAndLabels(params)Fetches the list of artists and labels followed by a fan.
\n\n**Params**\n\n- `params`: ([FanAPIGetItemsParams](docs/api/interfaces/FanAPIGetItemsParams.md))\n - `target`: (string | [FanItemsContinuation](docs/api/interfaces/FanItemsContinuation.md)) (*optional*) if username (string) is specified, returns the first batch of artists and labels. To obtain further items, call the method again but, instead of username, pass `continuation` from the result of the first call. If there are no further items available, `continuation` will be `null`.\n - `imageFormat`: (string | number | [ImageFormat](docs/api/interfaces/ImageFormat.md)) (*optional*)\n\nIf `target` is not specified, result will be obtained for the user of the [session](#user-sessions) tied to the `BandcampFetch` instance.\n\n**Returns**\n\nPromise resolving to ([FanPageItemsResult](docs/api/interfaces/FanPageItemsResult.md) | [FanContinuationItemsResult](docs/api/interfaces/FanContinuationItemsResult.md))<[UserKind](docs/api/interfaces/UserKind.md)>.\n\n---\ngetFollowingGenres(params)Fetches the list of genres followed by a fan.
\n\nEach genre is actually a Bandcamp tag, so you can, for example, pass its `url` to `getReleases()` of the [Tag API](#tag-api).\n\n**Params**\n\n- `params`: ([FanAPIGetItemsParams](docs/api/interfaces/FanAPIGetItemsParams.md))\n - `target`: (string | [FanItemsContinuation](docs/api/interfaces/FanItemsContinuation.md)) (*optional*) if username (string) is specified, returns the first batch of genres. To obtain further items, call the method again but, instead of username, pass `continuation` from the result of the first call. If there are no further items available, `continuation` will be `null`.\n - `imageFormat`: (string | number | [ImageFormat](docs/api/interfaces/ImageFormat.md)) (*optional*)\n\nIf `target` is not specified, result will be obtained for the user of the [session](#user-sessions) tied to the `BandcampFetch` instance.\n\n**Returns**\n\nPromise resolving to ([FanPageItemsResult](docs/api/interfaces/FanPageItemsResult.md) | [FanContinuationItemsResult](docs/api/interfaces/FanContinuationItemsResult.md))<[Tag](docs/api/interfaces/Tag.md)>.\n\n---\nlist(params)Fetches the list of playlists created by a fan.
\n\n**Params**\n\n- `params`: ([PlaylistAPIListParams](docs/api/type-aliases/PlaylistAPIListParams.md))\n - Either:\n - `fanId`: (number) the ID of the fan; or\n - `continuation`: ([PlaylistListContinuation](docs/api/interfaces/PlaylistListContinuation.md)) continuation data obtained from previous request; used for fetching further items in the list.\n - `imageFormat`: (string | number | [ImageFormat](docs/api/interfaces/ImageFormat.md)) (*optional*)\n\n**Returns**\n\nPromise resolving to [PlaylistList](docs/api/interfaces/PlaylistList.md).\n\n---\ngetPlaylist(params)Fetches full details about the playlist referred to by params.playlistUrl.
getAdditionalTracks(params)A playlist fetched via getPlaylist() contains full information for the first 30 tracks. Additional tracks only have their IDs stored in additionalTrackIds. Use getAdditionalTracks() to fetch full information for these additional tracks.
all(params) / artistsAndLabels(params) / albums(params) / tracks(params) / fans(params)getSuggestions(params)Fetches autocomplete suggestions for tags and locations, based on partial and full matches against `params.query`.
\n\nThe `value` property of returned suggestions can be used to set the `location` or `tags` property (as the case may be) of `params.filters` that is passed into `getReleases()` of the [Tag API](#tag-api).\n\n**Params**\n\n- `params`: ([AutocompleteAPIGetSuggestionsParams](docs/api/interfaces/AutocompleteAPIGetSuggestionsParams.md))\n - `query`: (string)\n - `itemType`: ([AutocompleteItemType](docs/api/enums/AutocompleteItemType.md)) 'Tag' or 'Location'\n - `limit`: (number) (*optional*) (only for `ItemType.Location`) the maximum number of results to return; 5 if omitted.\n\n**Returns**\n\n- If `params.itemType` is `AutocompleteItemType.Tag`, a Promise resolving to Array<[AutocompleteTag](docs/api/interfaces/AutoCompleteTag.md)>.\n- If `params.itemType` is `AutocompleteItemType.Location`, a Promise resolving to Array<[AutocompleteLocation](docs/api/interfaces/AutocompleteLocation.md)>.\n\n---\ntest(url)Tests validity of the stream given by `url`.
\n\n**Params**\n\n- `url`: (string) the URL of the stream to test\n\n**Returns**\n\nPromise resolving to [StreamTestResult](docs/api/interfaces/StreamTestResult.md):\n- `ok`: (boolean) whether the stream is valid\n- `status`: (number) the HTTP response status code returned by the test\n\n---\nrefresh(url)Refreshes a stream URL.
\n\n**Params**\n\n- `url`: (string) the URL of the stream to refresh\n\n**Returns**\n\nPromise resolving to the refreshed URL of the stream or `null` if no valid result was obtained.\n\n---\nsetTTL(type, ttl)Sets the expiry time, in seconds, of cache entries for the given data type.
\n\n**Params**\n\n- `type`: ([CacheDataType](docs/api/enums/CacheDataType.md))\n- `TTL`: (number) expiry time in seconds (default: 300 for `CacheDataType.Page` and 3600 for `CacheDataType.Constants`)\n\n---\nsetMaxPages(maxPages)Sets the maximum number of pages that can be stored in the cache. A negative value means unlimited. Default: 10.
\n\n**Params**\n\n- `maxPages`: (number)\n\n---\nclear([type])Clears the cache entries for the specified data type (or all entries if no data type specified).
\n\n**Params**\n\n- `type`: ([CacheDataType](docs/api/enums/CacheDataType.md)) (*optional*)\n\n---\n