{"id":24719207,"url":"https://github.com/lionralfs/discogs-client","last_synced_at":"2025-07-29T06:09:56.939Z","repository":{"id":39747504,"uuid":"445883326","full_name":"lionralfs/discogs-client","owner":"lionralfs","description":"A JavaScript Discogs Client for browsers and Node.js (ESM and CommonJS)","archived":false,"fork":false,"pushed_at":"2025-04-30T08:55:56.000Z","size":2264,"stargazers_count":29,"open_issues_count":13,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-07-19T08:02:30.304Z","etag":null,"topics":["discogs","discogs-client","esmodules","javascript","nodejs","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lionralfs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-01-08T17:23:21.000Z","updated_at":"2025-06-25T18:04:47.000Z","dependencies_parsed_at":"2023-10-01T19:46:37.069Z","dependency_job_id":"6ef50f4e-d9d6-40fb-9642-15136926c320","html_url":"https://github.com/lionralfs/discogs-client","commit_stats":{"total_commits":252,"total_committers":11,"mean_commits":22.90909090909091,"dds":0.5595238095238095,"last_synced_commit":"7f8a31f6eaceb40688ef80987ca5822e78923605"},"previous_names":["lionralfs/disconnect"],"tags_count":59,"template":false,"template_full_name":null,"purl":"pkg:github/lionralfs/discogs-client","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lionralfs%2Fdiscogs-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lionralfs%2Fdiscogs-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lionralfs%2Fdiscogs-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lionralfs%2Fdiscogs-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lionralfs","download_url":"https://codeload.github.com/lionralfs/discogs-client/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lionralfs%2Fdiscogs-client/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267639062,"owners_count":24119768,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-29T02:00:12.549Z","response_time":2574,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["discogs","discogs-client","esmodules","javascript","nodejs","typescript"],"created_at":"2025-01-27T11:16:59.638Z","updated_at":"2025-07-29T06:09:56.919Z","avatar_url":"https://github.com/lionralfs.png","language":"TypeScript","readme":"[![npm](https://img.shields.io/npm/v/@lionralfs/discogs-client)](https://www.npmjs.com/package/@lionralfs/discogs-client)\n![npm type definitions](https://img.shields.io/npm/types/@lionralfs/discogs-client)\n![node-current](https://img.shields.io/node/v/@lionralfs/discogs-client)\n![Libraries.io dependency status for latest release](https://img.shields.io/librariesio/release/npm/@lionralfs/discogs-client)\n![build status](https://github.com/lionralfs/discogs-client/actions/workflows/node.js.yml/badge.svg?branch=main)\n\n# `discogs-client`\n\n## About\n\n`discogs-client` is a [Node.js](https://nodejs.org) and browser client library that connects with the [Discogs.com API v2.0](https://www.discogs.com/developers/).\n\nThis library is a fork of the [original library](https://github.com/bartve/disconnect) which does the following:\n\n-   uses ES Modules\n-   uses esbuild to provide a bundle that is consumable by either:\n    -   node via ESM\n    -   node via CommonJS\n    -   browsers (where node-fetch is replaced with native window.fetch)\n-   uses TypeScript (and generating type declarations) for typed parameters and API results\n-   adds docs and type info via JSDoc (for non-TypeScript users)\n-   removes callbacks in favor of Promises\n-   adds support for all remaining Discogs endpoints\n-   adds more tests\n\n## Features\n\n-   Covers all API [endpoints](#structure)\n-   Supports [pagination](#pagination), [rate limiting](#rate-limiting) and [throttling](#throttling)\n-   API calls return a native JS [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)\n-   Easy access to protected endpoints with `Discogs Auth`\n-   Includes OAuth 1.0a tools. Just plug in your consumer key and secret and do the OAuth dance\n-   API functions grouped in their own namespace for easy access and isolation\n\n## Installation\n\n```\nnpm install @lionralfs/discogs-client\n```\n\n## Usage\n\n### Quick start\n\nHere are some basic usage examples that connect with the public API. Error handling has been left out for demonstrational purposes.\n\n#### Importing the library\n\n```js\n// in modern JS/TS\nimport { DiscogsClient } from '@lionralfs/discogs-client';\n\n// in commonjs environments\nconst { DiscogsClient } = require('@lionralfs/discogs-client/commonjs');\n\n// in browser environments\nimport { DiscogsClient } from '@lionralfs/discogs-client/browser';\n```\n\n#### Go!\n\nGet the release data for a release with the id 176126.\n\n```js\nlet db = new DiscogsClient().database();\ndb.getRelease(176126).then(function ({ rateLimit, data }) {\n    console.log(data);\n});\n```\n\nSet your own custom [User-Agent](http://www.discogs.com/developers/#page:home,header:home-general-information). This is optional as when omitted it will set a default one with the value `@lionralfs/discogs-client/x.x.x` where `x.x.x` is the installed version of this library.\n\n```js\nlet client = new DiscogsClient({ userAgent: 'MyUserAgent/1.0' });\n```\n\nGet page 2 of USER_NAME's public collection showing 75 releases.\nThe second param is the collection folder ID where 0 is always the \"All\" folder.\n\n```js\nlet col = new DiscogsClient().user().collection();\ncol.getReleases('USER_NAME', 0, { page: 2, per_page: 75 }).then(function ({ data }) {\n    console.log(data);\n});\n```\n\n### Promises\n\nThe API functions return a native JS [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) for easy chaining.\n\n```js\nlet db = client.database();\ndb.search({ query: 'dark side of the moon', type: 'master' })\n    .then(function ({ data }) {\n        return db.getMaster(data.results[0].id);\n    })\n    .then(function ({ data }) {\n        return db.getArtist(data.artists[0].id);\n    })\n    .then(function ({ data }) {\n        console.log(data.name);\n    });\n```\n\n### Output format\n\nUser, artist and label profiles can be formatted in different ways: `plaintext`, `html` and `discogs`. The client defaults to `discogs`, but the output format can be set for each client instance.\n\n```js\n// Set the output format to HTML\nlet client = new DiscogsClient().setConfig({ outputFormat: 'html' });\n```\n\n### Discogs Auth\n\nJust provide the client constructor with your preferred way of [authentication](https://www.discogs.com/developers/#page:authentication).\n\n```js\n// Authenticate by user token\nlet client = new DiscogsClient({ auth: { userToken: 'YOUR_USER_TOKEN' } });\n\n// Authenticate by consumer key and secret\nlet client = new DiscogsClient({\n    auth: {\n        method: 'discogs',\n        consumerKey: 'YOUR_CONSUMER_KEY',\n        consumerSecret: 'YOUR_CONSUMER_SECRET',\n    },\n});\n```\n\nThe User-Agent can still be passed for authenticated calls.\n\n```js\nlet client = new DiscogsClient({\n    userAgent: 'MyUserAgent/1.0',\n    auth: { userToken: 'YOUR_USER_TOKEN' },\n});\n```\n\n### OAuth\n\nBelow are the steps that involve getting a valid OAuth access token from Discogs.\n\n#### 1. Get a request token\n\n```js\nlet oAuth = new DiscogsOAuth('YOUR_CONSUMER_KEY', 'YOUR_CONSUMER_SECRET');\nlet { token, tokenSecret, authorizeUrl } = await oAuth.getRequestToken('https://your-domain.com/callback');\n\n// store token and tokenSecret in a cookie for example\n// redirect user to authorizeUrl\n```\n\n#### 2. Authorize\n\nAfter redirection to the Discogs authorize URL in step 1, authorize the application.\n\n#### 3. Get an access token\n\n```js\n// in the callback endpoint, capture the oauth_verifier query parameter\n// use the token and tokenSecret from step 1 to get an access token/secret\nlet { accessToken, accessTokenSecret } = await oAuth.getAccessToken(token, tokenSecret, oauth_verifier);\n```\n\n#### 4. Make OAuth calls\n\nInstantiate a new DiscogsClient class with the required auth arguments to make requests on behalf of the authenticated user.\n\n```js\nlet client = new DiscogsClient({\n    auth: {\n        method: 'oauth',\n        consumerKey: consumerKey,\n        consumerSecret: consumerSecret,\n        accessToken: accessToken,\n        accessTokenSecret: accessTokenSecret,\n    },\n});\n\nlet response = await client.getIdentity();\nconsole.log(response.data.username);\n```\n\n### Pagination\n\nDiscogs [paginates]() certain collections, as they would otherwise be too much to return for a single API call. You may use the `page` and `per_page` options in each call to query certain pages. If you don't pass these options, they fall back to the Discogs defaults, which are `1` and `50` respectively (the first 50 results on the first page).\n\nIn the `result.data` object, you'll find a `pagination` key, which contains some info returned by the Discogs API such as the total number of items and pages.\n\nHere's a short example of how to use pagination arguments:\n\n```js\n// retrieves an artist's releases (25 per page, 2nd page)\nlet result = await client.database().getArtistReleases(108713, { per_page: 25, page: 2 });\n\nconsole.log(result.data.pagination);\n// {\n//   page: 2,\n//   pages: 54,\n//   per_page: 25,\n//   items: 1331,\n//   urls: {\n//     first: 'https://api.discogs.com/artists/108713/releases?per_page=25\u0026page=1',\n//     last: 'https://api.discogs.com/artists/108713/releases?per_page=25\u0026page=54',\n//     prev: 'https://api.discogs.com/artists/108713/releases?per_page=25\u0026page=1',\n//     next: 'https://api.discogs.com/artists/108713/releases?per_page=25\u0026page=3'\n//   }\n// }\n```\n\n### Rate Limiting\n\nThe Discogs API imposes certain [rate limits](https://www.discogs.com/developers/#page:home,header:home-rate-limiting) on consumers, varying in allowed calls per minute depending on your authentication status. The API responds with your current quota in HTTP headers for each API call. These are passed to you as a `rateLimit` object on the response:\n\n```js\nlet response = await client.database().getArtistReleases(108713);\nconsole.log(response.rateLimit); // → { limit: 25, used: 4, remaining: 21 }\n```\n\n### Throttling\n\nThe client implements [exponential backoff](https://en.wikipedia.org/wiki/Exponential_backoff) when encountering Discogs-API responses with status code `429 Too Many Requests`. The exponential backoff can be configured via the following parameters:\n\n```js\nclient.setConfig({\n    exponentialBackoffIntervalMs: 2000,\n    exponentialBackoffMaxRetries: 5,\n    exponentialBackoffRate: 2.7,\n});\n```\n\n\u003e **Note**: By default, the `exponentialBackoffMaxRetries` is 0, essentially turning off throttling.\n\n## Structure\n\nThe global library structure looks as follows:\n\n```\nnew DiscogsClient() -\u003e database()\n                        -\u003e getArtist\n                        -\u003e getArtistReleases\n                        -\u003e getRelease\n                        -\u003e getReleaseRating\n                        -\u003e setReleaseRating\n                        -\u003e getReleaseCommunityRating\n                        -\u003e getReleaseStats\n                        -\u003e getMaster\n                        -\u003e getMasterVersions\n                        -\u003e getLabel\n                        -\u003e getLabelReleases\n                        -\u003e search\n                    -\u003e marketplace()\n                        -\u003e getInventory\n                        -\u003e getListing\n                        -\u003e addListing\n                        -\u003e editListing\n                        -\u003e deleteListing\n                        -\u003e getOrders\n                        -\u003e getOrder\n                        -\u003e editOrder\n                        -\u003e getOrderMessages\n                        -\u003e addOrderMessage\n                        -\u003e getFee\n                        -\u003e getPriceSuggestions\n                        -\u003e getReleaseStats\n                    -\u003e inventory()\n                        -\u003e exportInventory\n                        -\u003e getExports\n                        -\u003e getExport\n                        -\u003e downloadExport\n                    -\u003e user()\n                        -\u003e getProfile\n                        -\u003e editProfile\n                        -\u003e getInventory\n                        -\u003e getIdentity\n                        -\u003e getContributions\n                        -\u003e getSubmissions\n                        -\u003e getLists\n                        -\u003e collection()\n                            -\u003e getFolders\n                            -\u003e getFolder\n                            -\u003e addFolder\n                            -\u003e setFolderName\n                            -\u003e deleteFolder\n                            -\u003e getReleases\n                            -\u003e getReleaseInstances\n                            -\u003e addRelease\n                            -\u003e editRelease\n                            -\u003e removeRelease\n                            -\u003e getFields\n                            -\u003e editInstanceNote\n                            -\u003e getValue\n                        -\u003e wantlist()\n                            -\u003e getReleases\n                            -\u003e addRelease\n                            -\u003e editNotes\n                            -\u003e removeRelease\n                        -\u003e list()\n                            -\u003e getItems\nnew DiscogsOAuth()  -\u003e getRequestToken\n                    -\u003e getAccessToken\n```\n\n## Resources\n\n-   [This fork's origin](https://github.com/bartve/disconnect)\n-   [Discogs API documentation](https://www.discogs.com/developers/)\n-   [OAuth Core 1.0 Revision A](https://oauth.net/core/1.0a/)\n\n## License\n\nMIT\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flionralfs%2Fdiscogs-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flionralfs%2Fdiscogs-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flionralfs%2Fdiscogs-client/lists"}