Changelog for Release server-2024-01-01 (#9863)

* Update Changelog

* Update CHANGELOG.md

* prettier

---------

Co-authored-by: release[bot] <actions@users.noreply.github.com>
Co-authored-by: chris48s <chris48s@users.noreply.github.com>
Co-authored-by: chris48s <git@chris-shaw.dev>

.github/actions/close-bot/action.yml

@@ -1,12 +0,0 @@
-name: 'Auto Approve'
-description: 'Automatically approve/close selected pull requests for shields.io'
-branding:
-  icon: 'check-circle'
-  color: 'green'
-inputs:
-  github-token:
-    description: 'The GITHUB_TOKEN secret'
-    required: true
-runs:
-  using: 'node16'
-  main: 'index.js'

.github/actions/close-bot/helpers.js

@@ -1,68 +0,0 @@
-'use strict'
-
-function findChangelogStart(lines) {
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i]
-    if (
-      line === '<summary>Changelog</summary>' &&
-      lines[i + 2] === '<blockquote>'
-    ) {
-      return i + 3
-    }
-  }
-  return null
-}
-
-function findChangelogEnd(lines, start) {
-  for (let i = start; i < lines.length; i++) {
-    const line = lines[i]
-    if (line === '</blockquote>') {
-      return i
-    }
-  }
-  return null
-}
-
-function allChangelogLinesAreVersionBump(changelogLines) {
-  return (
-    changelogLines.length > 0 &&
-    changelogLines.length ===
-      changelogLines.filter(line =>
-        line.includes('Version bump only for package'),
-      ).length
-  )
-}
-
-function isPointlessVersionBump(body) {
-  const pointlessBumpLinks = [
-    'https://github.com/typescript-eslint/typescript-eslint',
-  ]
-
-  const lines = body.split(/\r?\n/)
-  if (!pointlessBumpLinks.some(link => lines[0].includes(link))) {
-    return false
-  }
-  const start = findChangelogStart(lines)
-  const end = findChangelogEnd(lines, start)
-  if (!start || !end) {
-    return false
-  }
-  const changelogLines = lines
-    .slice(start, end)
-    .filter(line => !line.startsWith('<h'))
-    .filter(line => !line.startsWith('<p>All notable changes'))
-    .filter(
-      line =>
-        !line.startsWith('See <a href="https://conventionalcommits.org">'),
-    )
-    .filter(line => !line.startsWith('<!--'))
-    .filter(
-      line =>
-        !line.startsWith(
-          '<p><a href="https://www.gatsbyjs.com/docs/reference/release-notes/',
-        ),
-    )
-  return allChangelogLinesAreVersionBump(changelogLines)
-}
-
-module.exports = { isPointlessVersionBump }

.github/actions/close-bot/index.js

@@ -1,38 +0,0 @@
-'use strict'
-
-const core = require('@actions/core')
-const github = require('@actions/github')
-const { isPointlessVersionBump } = require('./helpers')
-
-async function run() {
-  try {
-    const token = core.getInput('github-token', { required: true })
-
-    const { pull_request: pr } = github.context.payload
-    if (!pr) {
-      throw new Error('Event payload missing `pull_request`')
-    }
-
-    const client = github.getOctokit(token)
-
-    if (
-      ['dependabot[bot]', 'dependabot-preview[bot]'].includes(pr.user.login)
-    ) {
-      if (isPointlessVersionBump(pr.body)) {
-        core.debug(`Closing pull request #${pr.number}`)
-        await client.rest.pulls.update({
-          owner: github.context.repo.owner,
-          repo: github.context.repo.repo,
-          pull_number: pr.number,
-          state: 'closed',
-        })
-
-        core.debug('Done.')
-      }
-    }
-  } catch (error) {
-    core.setFailed(error.message)
-  }
-}
-
-run()

.github/actions/close-bot/package-lock.json

@@ -1,431 +0,0 @@
-{
-  "name": "close-bot",
-  "version": "0.0.0",
-  "lockfileVersion": 2,
-  "requires": true,
-  "packages": {
-    "": {
-      "name": "close-bot",
-      "version": "0.0.0",
-      "license": "CC0",
-      "dependencies": {
-        "@actions/core": "^1.10.0",
-        "@actions/github": "^5.1.1"
-      }
-    },
-    "node_modules/@actions/core": {
-      "version": "1.10.0",
-      "resolved": "https://registry.npmjs.org/@actions/core/-/core-1.10.0.tgz",
-      "integrity": "sha512-2aZDDa3zrrZbP5ZYg159sNoLRb61nQ7awl5pSvIq5Qpj81vwDzdMRKzkWJGJuwVvWpvZKx7vspJALyvaaIQyug==",
-      "dependencies": {
-        "@actions/http-client": "^2.0.1",
-        "uuid": "^8.3.2"
-      }
-    },
-    "node_modules/@actions/github": {
-      "version": "5.1.1",
-      "resolved": "https://registry.npmjs.org/@actions/github/-/github-5.1.1.tgz",
-      "integrity": "sha512-Nk59rMDoJaV+mHCOJPXuvB1zIbomlKS0dmSIqPGxd0enAXBnOfn4VWF+CGtRCwXZG9Epa54tZA7VIRlJDS8A6g==",
-      "dependencies": {
-        "@actions/http-client": "^2.0.1",
-        "@octokit/core": "^3.6.0",
-        "@octokit/plugin-paginate-rest": "^2.17.0",
-        "@octokit/plugin-rest-endpoint-methods": "^5.13.0"
-      }
-    },
-    "node_modules/@actions/http-client": {
-      "version": "2.0.1",
-      "resolved": "https://registry.npmjs.org/@actions/http-client/-/http-client-2.0.1.tgz",
-      "integrity": "sha512-PIXiMVtz6VvyaRsGY268qvj57hXQEpsYogYOu2nrQhlf+XCGmZstmuZBbAybUl1nQGnvS1k1eEsQ69ZoD7xlSw==",
-      "dependencies": {
-        "tunnel": "^0.0.6"
-      }
-    },
-    "node_modules/@octokit/auth-token": {
-      "version": "2.5.0",
-      "resolved": "https://registry.npmjs.org/@octokit/auth-token/-/auth-token-2.5.0.tgz",
-      "integrity": "sha512-r5FVUJCOLl19AxiuZD2VRZ/ORjp/4IN98Of6YJoJOkY75CIBuYfmiNHGrDwXr+aLGG55igl9QrxX3hbiXlLb+g==",
-      "dependencies": {
-        "@octokit/types": "^6.0.3"
-      }
-    },
-    "node_modules/@octokit/core": {
-      "version": "3.6.0",
-      "resolved": "https://registry.npmjs.org/@octokit/core/-/core-3.6.0.tgz",
-      "integrity": "sha512-7RKRKuA4xTjMhY+eG3jthb3hlZCsOwg3rztWh75Xc+ShDWOfDDATWbeZpAHBNRpm4Tv9WgBMOy1zEJYXG6NJ7Q==",
-      "dependencies": {
-        "@octokit/auth-token": "^2.4.4",
-        "@octokit/graphql": "^4.5.8",
-        "@octokit/request": "^5.6.3",
-        "@octokit/request-error": "^2.0.5",
-        "@octokit/types": "^6.0.3",
-        "before-after-hook": "^2.2.0",
-        "universal-user-agent": "^6.0.0"
-      }
-    },
-    "node_modules/@octokit/endpoint": {
-      "version": "6.0.12",
-      "resolved": "https://registry.npmjs.org/@octokit/endpoint/-/endpoint-6.0.12.tgz",
-      "integrity": "sha512-lF3puPwkQWGfkMClXb4k/eUT/nZKQfxinRWJrdZaJO85Dqwo/G0yOC434Jr2ojwafWJMYqFGFa5ms4jJUgujdA==",
-      "dependencies": {
-        "@octokit/types": "^6.0.3",
-        "is-plain-object": "^5.0.0",
-        "universal-user-agent": "^6.0.0"
-      }
-    },
-    "node_modules/@octokit/graphql": {
-      "version": "4.8.0",
-      "resolved": "https://registry.npmjs.org/@octokit/graphql/-/graphql-4.8.0.tgz",
-      "integrity": "sha512-0gv+qLSBLKF0z8TKaSKTsS39scVKF9dbMxJpj3U0vC7wjNWFuIpL/z76Qe2fiuCbDRcJSavkXsVtMS6/dtQQsg==",
-      "dependencies": {
-        "@octokit/request": "^5.6.0",
-        "@octokit/types": "^6.0.3",
-        "universal-user-agent": "^6.0.0"
-      }
-    },
-    "node_modules/@octokit/openapi-types": {
-      "version": "11.2.0",
-      "resolved": "https://registry.npmjs.org/@octokit/openapi-types/-/openapi-types-11.2.0.tgz",
-      "integrity": "sha512-PBsVO+15KSlGmiI8QAzaqvsNlZlrDlyAJYcrXBCvVUxCp7VnXjkwPoFHgjEJXx3WF9BAwkA6nfCUA7i9sODzKA=="
-    },
-    "node_modules/@octokit/plugin-paginate-rest": {
-      "version": "2.17.0",
-      "resolved": "https://registry.npmjs.org/@octokit/plugin-paginate-rest/-/plugin-paginate-rest-2.17.0.tgz",
-      "integrity": "sha512-tzMbrbnam2Mt4AhuyCHvpRkS0oZ5MvwwcQPYGtMv4tUa5kkzG58SVB0fcsLulOZQeRnOgdkZWkRUiyBlh0Bkyw==",
-      "dependencies": {
-        "@octokit/types": "^6.34.0"
-      },
-      "peerDependencies": {
-        "@octokit/core": ">=2"
-      }
-    },
-    "node_modules/@octokit/plugin-rest-endpoint-methods": {
-      "version": "5.13.0",
-      "resolved": "https://registry.npmjs.org/@octokit/plugin-rest-endpoint-methods/-/plugin-rest-endpoint-methods-5.13.0.tgz",
-      "integrity": "sha512-uJjMTkN1KaOIgNtUPMtIXDOjx6dGYysdIFhgA52x4xSadQCz3b/zJexvITDVpANnfKPW/+E0xkOvLntqMYpviA==",
-      "dependencies": {
-        "@octokit/types": "^6.34.0",
-        "deprecation": "^2.3.1"
-      },
-      "peerDependencies": {
-        "@octokit/core": ">=3"
-      }
-    },
-    "node_modules/@octokit/request": {
-      "version": "5.6.3",
-      "resolved": "https://registry.npmjs.org/@octokit/request/-/request-5.6.3.tgz",
-      "integrity": "sha512-bFJl0I1KVc9jYTe9tdGGpAMPy32dLBXXo1dS/YwSCTL/2nd9XeHsY616RE3HPXDVk+a+dBuzyz5YdlXwcDTr2A==",
-      "dependencies": {
-        "@octokit/endpoint": "^6.0.1",
-        "@octokit/request-error": "^2.1.0",
-        "@octokit/types": "^6.16.1",
-        "is-plain-object": "^5.0.0",
-        "node-fetch": "^2.6.7",
-        "universal-user-agent": "^6.0.0"
-      }
-    },
-    "node_modules/@octokit/request-error": {
-      "version": "2.1.0",
-      "resolved": "https://registry.npmjs.org/@octokit/request-error/-/request-error-2.1.0.tgz",
-      "integrity": "sha512-1VIvgXxs9WHSjicsRwq8PlR2LR2x6DwsJAaFgzdi0JfJoGSO8mYI/cHJQ+9FbN21aa+DrgNLnwObmyeSC8Rmpg==",
-      "dependencies": {
-        "@octokit/types": "^6.0.3",
-        "deprecation": "^2.0.0",
-        "once": "^1.4.0"
-      }
-    },
-    "node_modules/@octokit/types": {
-      "version": "6.34.0",
-      "resolved": "https://registry.npmjs.org/@octokit/types/-/types-6.34.0.tgz",
-      "integrity": "sha512-s1zLBjWhdEI2zwaoSgyOFoKSl109CUcVBCc7biPJ3aAf6LGLU6szDvi31JPU7bxfla2lqfhjbbg/5DdFNxOwHw==",
-      "dependencies": {
-        "@octokit/openapi-types": "^11.2.0"
-      }
-    },
-    "node_modules/before-after-hook": {
-      "version": "2.2.2",
-      "resolved": "https://registry.npmjs.org/before-after-hook/-/before-after-hook-2.2.2.tgz",
-      "integrity": "sha512-3pZEU3NT5BFUo/AD5ERPWOgQOCZITni6iavr5AUw5AUwQjMlI0kzu5btnyD39AF0gUEsDPwJT+oY1ORBJijPjQ=="
-    },
-    "node_modules/deprecation": {
-      "version": "2.3.1",
-      "resolved": "https://registry.npmjs.org/deprecation/-/deprecation-2.3.1.tgz",
-      "integrity": "sha512-xmHIy4F3scKVwMsQ4WnVaS8bHOx0DmVwRywosKhaILI0ywMDWPtBSku2HNxRvF7jtwDRsoEwYQSfbxj8b7RlJQ=="
-    },
-    "node_modules/is-plain-object": {
-      "version": "5.0.0",
-      "resolved": "https://registry.npmjs.org/is-plain-object/-/is-plain-object-5.0.0.tgz",
-      "integrity": "sha512-VRSzKkbMm5jMDoKLbltAkFQ5Qr7VDiTFGXxYFXXowVj387GeGNOCsOH6Msy00SGZ3Fp84b1Naa1psqgcCIEP5Q==",
-      "engines": {
-        "node": ">=0.10.0"
-      }
-    },
-    "node_modules/node-fetch": {
-      "version": "2.6.7",
-      "resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-2.6.7.tgz",
-      "integrity": "sha512-ZjMPFEfVx5j+y2yF35Kzx5sF7kDzxuDj6ziH4FFbOp87zKDZNx8yExJIb05OGF4Nlt9IHFIMBkRl41VdvcNdbQ==",
-      "dependencies": {
-        "whatwg-url": "^5.0.0"
-      },
-      "engines": {
-        "node": "4.x || >=6.0.0"
-      },
-      "peerDependencies": {
-        "encoding": "^0.1.0"
-      },
-      "peerDependenciesMeta": {
-        "encoding": {
-          "optional": true
-        }
-      }
-    },
-    "node_modules/once": {
-      "version": "1.4.0",
-      "resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz",
-      "integrity": "sha1-WDsap3WWHUsROsF9nFC6753Xa9E=",
-      "dependencies": {
-        "wrappy": "1"
-      }
-    },
-    "node_modules/tr46": {
-      "version": "0.0.3",
-      "resolved": "https://registry.npmjs.org/tr46/-/tr46-0.0.3.tgz",
-      "integrity": "sha1-gYT9NH2snNwYWZLzpmIuFLnZq2o="
-    },
-    "node_modules/tunnel": {
-      "version": "0.0.6",
-      "resolved": "https://registry.npmjs.org/tunnel/-/tunnel-0.0.6.tgz",
-      "integrity": "sha512-1h/Lnq9yajKY2PEbBadPXj3VxsDDu844OnaAo52UVmIzIvwwtBPIuNvkjuzBlTWpfJyUbG3ez0KSBibQkj4ojg==",
-      "engines": {
-        "node": ">=0.6.11 <=0.7.0 || >=0.7.3"
-      }
-    },
-    "node_modules/universal-user-agent": {
-      "version": "6.0.0",
-      "resolved": "https://registry.npmjs.org/universal-user-agent/-/universal-user-agent-6.0.0.tgz",
-      "integrity": "sha512-isyNax3wXoKaulPDZWHQqbmIx1k2tb9fb3GGDBRxCscfYV2Ch7WxPArBsFEG8s/safwXTT7H4QGhaIkTp9447w=="
-    },
-    "node_modules/uuid": {
-      "version": "8.3.2",
-      "resolved": "https://registry.npmjs.org/uuid/-/uuid-8.3.2.tgz",
-      "integrity": "sha512-+NYs2QeMWy+GWFOEm9xnn6HCDp0l7QBD7ml8zLUmJ+93Q5NF0NocErnwkTkXVFNiX3/fpC6afS8Dhb/gz7R7eg==",
-      "bin": {
-        "uuid": "dist/bin/uuid"
-      }
-    },
-    "node_modules/webidl-conversions": {
-      "version": "3.0.1",
-      "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-3.0.1.tgz",
-      "integrity": "sha1-JFNCdeKnvGvnvIZhHMFq4KVlSHE="
-    },
-    "node_modules/whatwg-url": {
-      "version": "5.0.0",
-      "resolved": "https://registry.npmjs.org/whatwg-url/-/whatwg-url-5.0.0.tgz",
-      "integrity": "sha1-lmRU6HZUYuN2RNNib2dCzotwll0=",
-      "dependencies": {
-        "tr46": "~0.0.3",
-        "webidl-conversions": "^3.0.0"
-      }
-    },
-    "node_modules/wrappy": {
-      "version": "1.0.2",
-      "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz",
-      "integrity": "sha1-tSQ9jz7BqjXxNkYFvA0QNuMKtp8="
-    }
-  },
-  "dependencies": {
-    "@actions/core": {
-      "version": "1.10.0",
-      "resolved": "https://registry.npmjs.org/@actions/core/-/core-1.10.0.tgz",
-      "integrity": "sha512-2aZDDa3zrrZbP5ZYg159sNoLRb61nQ7awl5pSvIq5Qpj81vwDzdMRKzkWJGJuwVvWpvZKx7vspJALyvaaIQyug==",
-      "requires": {
-        "@actions/http-client": "^2.0.1",
-        "uuid": "^8.3.2"
-      }
-    },
-    "@actions/github": {
-      "version": "5.1.1",
-      "resolved": "https://registry.npmjs.org/@actions/github/-/github-5.1.1.tgz",
-      "integrity": "sha512-Nk59rMDoJaV+mHCOJPXuvB1zIbomlKS0dmSIqPGxd0enAXBnOfn4VWF+CGtRCwXZG9Epa54tZA7VIRlJDS8A6g==",
-      "requires": {
-        "@actions/http-client": "^2.0.1",
-        "@octokit/core": "^3.6.0",
-        "@octokit/plugin-paginate-rest": "^2.17.0",
-        "@octokit/plugin-rest-endpoint-methods": "^5.13.0"
-      }
-    },
-    "@actions/http-client": {
-      "version": "2.0.1",
-      "resolved": "https://registry.npmjs.org/@actions/http-client/-/http-client-2.0.1.tgz",
-      "integrity": "sha512-PIXiMVtz6VvyaRsGY268qvj57hXQEpsYogYOu2nrQhlf+XCGmZstmuZBbAybUl1nQGnvS1k1eEsQ69ZoD7xlSw==",
-      "requires": {
-        "tunnel": "^0.0.6"
-      }
-    },
-    "@octokit/auth-token": {
-      "version": "2.5.0",
-      "resolved": "https://registry.npmjs.org/@octokit/auth-token/-/auth-token-2.5.0.tgz",
-      "integrity": "sha512-r5FVUJCOLl19AxiuZD2VRZ/ORjp/4IN98Of6YJoJOkY75CIBuYfmiNHGrDwXr+aLGG55igl9QrxX3hbiXlLb+g==",
-      "requires": {
-        "@octokit/types": "^6.0.3"
-      }
-    },
-    "@octokit/core": {
-      "version": "3.6.0",
-      "resolved": "https://registry.npmjs.org/@octokit/core/-/core-3.6.0.tgz",
-      "integrity": "sha512-7RKRKuA4xTjMhY+eG3jthb3hlZCsOwg3rztWh75Xc+ShDWOfDDATWbeZpAHBNRpm4Tv9WgBMOy1zEJYXG6NJ7Q==",
-      "requires": {
-        "@octokit/auth-token": "^2.4.4",
-        "@octokit/graphql": "^4.5.8",
-        "@octokit/request": "^5.6.3",
-        "@octokit/request-error": "^2.0.5",
-        "@octokit/types": "^6.0.3",
-        "before-after-hook": "^2.2.0",
-        "universal-user-agent": "^6.0.0"
-      }
-    },
-    "@octokit/endpoint": {
-      "version": "6.0.12",
-      "resolved": "https://registry.npmjs.org/@octokit/endpoint/-/endpoint-6.0.12.tgz",
-      "integrity": "sha512-lF3puPwkQWGfkMClXb4k/eUT/nZKQfxinRWJrdZaJO85Dqwo/G0yOC434Jr2ojwafWJMYqFGFa5ms4jJUgujdA==",
-      "requires": {
-        "@octokit/types": "^6.0.3",
-        "is-plain-object": "^5.0.0",
-        "universal-user-agent": "^6.0.0"
-      }
-    },
-    "@octokit/graphql": {
-      "version": "4.8.0",
-      "resolved": "https://registry.npmjs.org/@octokit/graphql/-/graphql-4.8.0.tgz",
-      "integrity": "sha512-0gv+qLSBLKF0z8TKaSKTsS39scVKF9dbMxJpj3U0vC7wjNWFuIpL/z76Qe2fiuCbDRcJSavkXsVtMS6/dtQQsg==",
-      "requires": {
-        "@octokit/request": "^5.6.0",
-        "@octokit/types": "^6.0.3",
-        "universal-user-agent": "^6.0.0"
-      }
-    },
-    "@octokit/openapi-types": {
-      "version": "11.2.0",
-      "resolved": "https://registry.npmjs.org/@octokit/openapi-types/-/openapi-types-11.2.0.tgz",
-      "integrity": "sha512-PBsVO+15KSlGmiI8QAzaqvsNlZlrDlyAJYcrXBCvVUxCp7VnXjkwPoFHgjEJXx3WF9BAwkA6nfCUA7i9sODzKA=="
-    },
-    "@octokit/plugin-paginate-rest": {
-      "version": "2.17.0",
-      "resolved": "https://registry.npmjs.org/@octokit/plugin-paginate-rest/-/plugin-paginate-rest-2.17.0.tgz",
-      "integrity": "sha512-tzMbrbnam2Mt4AhuyCHvpRkS0oZ5MvwwcQPYGtMv4tUa5kkzG58SVB0fcsLulOZQeRnOgdkZWkRUiyBlh0Bkyw==",
-      "requires": {
-        "@octokit/types": "^6.34.0"
-      }
-    },
-    "@octokit/plugin-rest-endpoint-methods": {
-      "version": "5.13.0",
-      "resolved": "https://registry.npmjs.org/@octokit/plugin-rest-endpoint-methods/-/plugin-rest-endpoint-methods-5.13.0.tgz",
-      "integrity": "sha512-uJjMTkN1KaOIgNtUPMtIXDOjx6dGYysdIFhgA52x4xSadQCz3b/zJexvITDVpANnfKPW/+E0xkOvLntqMYpviA==",
-      "requires": {
-        "@octokit/types": "^6.34.0",
-        "deprecation": "^2.3.1"
-      }
-    },
-    "@octokit/request": {
-      "version": "5.6.3",
-      "resolved": "https://registry.npmjs.org/@octokit/request/-/request-5.6.3.tgz",
-      "integrity": "sha512-bFJl0I1KVc9jYTe9tdGGpAMPy32dLBXXo1dS/YwSCTL/2nd9XeHsY616RE3HPXDVk+a+dBuzyz5YdlXwcDTr2A==",
-      "requires": {
-        "@octokit/endpoint": "^6.0.1",
-        "@octokit/request-error": "^2.1.0",
-        "@octokit/types": "^6.16.1",
-        "is-plain-object": "^5.0.0",
-        "node-fetch": "^2.6.7",
-        "universal-user-agent": "^6.0.0"
-      }
-    },
-    "@octokit/request-error": {
-      "version": "2.1.0",
-      "resolved": "https://registry.npmjs.org/@octokit/request-error/-/request-error-2.1.0.tgz",
-      "integrity": "sha512-1VIvgXxs9WHSjicsRwq8PlR2LR2x6DwsJAaFgzdi0JfJoGSO8mYI/cHJQ+9FbN21aa+DrgNLnwObmyeSC8Rmpg==",
-      "requires": {
-        "@octokit/types": "^6.0.3",
-        "deprecation": "^2.0.0",
-        "once": "^1.4.0"
-      }
-    },
-    "@octokit/types": {
-      "version": "6.34.0",
-      "resolved": "https://registry.npmjs.org/@octokit/types/-/types-6.34.0.tgz",
-      "integrity": "sha512-s1zLBjWhdEI2zwaoSgyOFoKSl109CUcVBCc7biPJ3aAf6LGLU6szDvi31JPU7bxfla2lqfhjbbg/5DdFNxOwHw==",
-      "requires": {
-        "@octokit/openapi-types": "^11.2.0"
-      }
-    },
-    "before-after-hook": {
-      "version": "2.2.2",
-      "resolved": "https://registry.npmjs.org/before-after-hook/-/before-after-hook-2.2.2.tgz",
-      "integrity": "sha512-3pZEU3NT5BFUo/AD5ERPWOgQOCZITni6iavr5AUw5AUwQjMlI0kzu5btnyD39AF0gUEsDPwJT+oY1ORBJijPjQ=="
-    },
-    "deprecation": {
-      "version": "2.3.1",
-      "resolved": "https://registry.npmjs.org/deprecation/-/deprecation-2.3.1.tgz",
-      "integrity": "sha512-xmHIy4F3scKVwMsQ4WnVaS8bHOx0DmVwRywosKhaILI0ywMDWPtBSku2HNxRvF7jtwDRsoEwYQSfbxj8b7RlJQ=="
-    },
-    "is-plain-object": {
-      "version": "5.0.0",
-      "resolved": "https://registry.npmjs.org/is-plain-object/-/is-plain-object-5.0.0.tgz",
-      "integrity": "sha512-VRSzKkbMm5jMDoKLbltAkFQ5Qr7VDiTFGXxYFXXowVj387GeGNOCsOH6Msy00SGZ3Fp84b1Naa1psqgcCIEP5Q=="
-    },
-    "node-fetch": {
-      "version": "2.6.7",
-      "resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-2.6.7.tgz",
-      "integrity": "sha512-ZjMPFEfVx5j+y2yF35Kzx5sF7kDzxuDj6ziH4FFbOp87zKDZNx8yExJIb05OGF4Nlt9IHFIMBkRl41VdvcNdbQ==",
-      "requires": {
-        "whatwg-url": "^5.0.0"
-      }
-    },
-    "once": {
-      "version": "1.4.0",
-      "resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz",
-      "integrity": "sha1-WDsap3WWHUsROsF9nFC6753Xa9E=",
-      "requires": {
-        "wrappy": "1"
-      }
-    },
-    "tr46": {
-      "version": "0.0.3",
-      "resolved": "https://registry.npmjs.org/tr46/-/tr46-0.0.3.tgz",
-      "integrity": "sha1-gYT9NH2snNwYWZLzpmIuFLnZq2o="
-    },
-    "tunnel": {
-      "version": "0.0.6",
-      "resolved": "https://registry.npmjs.org/tunnel/-/tunnel-0.0.6.tgz",
-      "integrity": "sha512-1h/Lnq9yajKY2PEbBadPXj3VxsDDu844OnaAo52UVmIzIvwwtBPIuNvkjuzBlTWpfJyUbG3ez0KSBibQkj4ojg=="
-    },
-    "universal-user-agent": {
-      "version": "6.0.0",
-      "resolved": "https://registry.npmjs.org/universal-user-agent/-/universal-user-agent-6.0.0.tgz",
-      "integrity": "sha512-isyNax3wXoKaulPDZWHQqbmIx1k2tb9fb3GGDBRxCscfYV2Ch7WxPArBsFEG8s/safwXTT7H4QGhaIkTp9447w=="
-    },
-    "uuid": {
-      "version": "8.3.2",
-      "resolved": "https://registry.npmjs.org/uuid/-/uuid-8.3.2.tgz",
-      "integrity": "sha512-+NYs2QeMWy+GWFOEm9xnn6HCDp0l7QBD7ml8zLUmJ+93Q5NF0NocErnwkTkXVFNiX3/fpC6afS8Dhb/gz7R7eg=="
-    },
-    "webidl-conversions": {
-      "version": "3.0.1",
-      "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-3.0.1.tgz",
-      "integrity": "sha1-JFNCdeKnvGvnvIZhHMFq4KVlSHE="
-    },
-    "whatwg-url": {
-      "version": "5.0.0",
-      "resolved": "https://registry.npmjs.org/whatwg-url/-/whatwg-url-5.0.0.tgz",
-      "integrity": "sha1-lmRU6HZUYuN2RNNib2dCzotwll0=",
-      "requires": {
-        "tr46": "~0.0.3",
-        "webidl-conversions": "^3.0.0"
-      }
-    },
-    "wrappy": {
-      "version": "1.0.2",
-      "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz",
-      "integrity": "sha1-tSQ9jz7BqjXxNkYFvA0QNuMKtp8="
-    }
-  }
-}

.github/actions/close-bot/package.json

@@ -1,16 +0,0 @@
-{
-  "name": "close-bot",
-  "version": "0.0.0",
-  "description": "",
-  "main": "index.js",
-  "private": true,
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
-  "author": "chris48s",
-  "license": "CC0",
-  "dependencies": {
-    "@actions/core": "^1.10.0",
-    "@actions/github": "^5.1.1"
-  }
-}

.github/actions/docusaurus-swizzled-warning/action.yml

@@ -0,0 +1,12 @@
+name: 'docusaurus-theme-openapi swizzled component changes warning'
+description: 'Check for changes in docusaurus-theme-openapi components which are swizzled and prints out a warning'
+branding:
+  icon: 'alert-triangle'
+  color: 'yellow'
+inputs:
+  github-token:
+    description: 'The GITHUB_TOKEN secret'
+    required: true
+runs:
+  using: 'node20'
+  main: 'index.js'

.github/actions/docusaurus-swizzled-warning/helpers.js

@@ -0,0 +1,105 @@
+'use strict'
+
+/**
+ * Returns info about all files changed in a PR (max 3000 results)
+ *
+ * @param {object} client hydrated octokit ready to use for GitHub Actions
+ * @param {string} owner repo owner
+ * @param {string} repo repo name
+ * @param {number} pullNumber pull request number
+ * @returns {object[]} array of object that describe pr changed files - see https://docs.github.com/en/rest/pulls/pulls?apiVersion=2022-11-28#list-pull-requests-files
+ */
+async function getAllFilesForPullRequest(client, owner, repo, pullNumber) {
+  const perPage = 100 // Max number of items per page
+  let page = 1 // Start with the first page
+  let allFiles = []
+  while (true) {
+    const response = await client.rest.pulls.listFiles({
+      owner,
+      repo,
+      pull_number: pullNumber,
+      per_page: perPage,
+      page,
+    })
+
+    if (response.data.length === 0) {
+      // Break the loop if no more results
+      break
+    }
+
+    allFiles = allFiles.concat(response.data)
+    page++ // Move to the next page
+  }
+  return allFiles
+}
+
+/**
+ * Get a list of files changed betwen two tags for a github repo
+ *
+ * @param {object} client hydrated octokit ready to use for GitHub Actions
+ * @param {string} owner repo owner
+ * @param {string} repo repo name
+ * @param {string} baseTag base tag
+ * @param {string} headTag head tag
+ * @returns {string[]} Array listing all changed files betwen the base tag and the head tag
+ */
+async function getChangedFilesBetweenTags(
+  client,
+  owner,
+  repo,
+  baseTag,
+  headTag,
+) {
+  const response = await client.rest.repos.compareCommits({
+    owner,
+    repo,
+    base: baseTag,
+    head: headTag,
+  })
+
+  return response.data.files.map(file => file.filename)
+}
+
+function findKeyEndingWith(obj, ending) {
+  for (const key in obj) {
+    if (key.endsWith(ending)) {
+      return key
+    }
+  }
+}
+
+/**
+ * Get large (>1MB) JSON file from git repo on at ref as a json object
+ *
+ * @param {object} client Hydrated octokit ready to use for GitHub Actions
+ * @param {string} owner Repo owner
+ * @param {string} repo Repo name
+ * @param {string} path Path of the file in repo relative to root directory
+ * @param {string} ref Git refrence (commit, branch, tag)
+ * @returns {string[]} Array listing all changed files betwen the base tag and the head tag
+ */
+async function getLargeJsonAtRef(client, owner, repo, path, ref) {
+  const fileSha = (
+    await client.rest.repos.getContent({
+      owner,
+      repo,
+      path,
+      ref,
+    })
+  ).data.sha
+  const fileBlob = (
+    await client.rest.git.getBlob({
+      owner,
+      repo,
+      file_sha: fileSha,
+    })
+  ).data.content
+  return JSON.parse(Buffer.from(fileBlob, 'base64').toString())
+}
+
+module.exports = {
+  getAllFilesForPullRequest,
+  getChangedFilesBetweenTags,
+  findKeyEndingWith,
+  getLargeJsonAtRef,
+}

.github/actions/docusaurus-swizzled-warning/index.js

@@ -0,0 +1,148 @@
+'use strict'
+
+const core = require('@actions/core')
+const github = require('@actions/github')
+const {
+  getAllFilesForPullRequest,
+  getChangedFilesBetweenTags,
+  findKeyEndingWith,
+  getLargeJsonAtRef,
+} = require('./helpers')
+
+async function run() {
+  try {
+    const token = core.getInput('github-token', { required: true })
+
+    const { pull_request: pr } = github.context.payload
+    if (!pr) {
+      throw new Error('Event payload missing `pull_request`')
+    }
+
+    const client = github.getOctokit(token)
+    const packageName = 'docusaurus-theme-openapi'
+    const packageParentName = 'docusaurus-preset-openapi'
+    const overideComponents = ['Curl', 'Response']
+    const messageTemplate = `<table><thead><tr><th colspan="2">
+      ⚠️ This PR contains changes to components of ${packageName} we've overridden
+    </th></tr>
+    <tr><th colspan="2">
+      We need to watch out for changes to the ${overideComponents.join(
+        ', ',
+      )} components
+    </th></tr></thead>
+    `
+
+    if (
+      !['dependabot[bot]', 'dependabot-preview[bot]'].includes(pr.user.login)
+    ) {
+      return
+    }
+    const files = await getAllFilesForPullRequest(
+      client,
+      github.context.repo.owner,
+      github.context.repo.repo,
+      pr.number,
+    )
+
+    const file = files.filter(f => f.filename === 'package-lock.json')[0]
+    if (file === undefined) {
+      return
+    }
+
+    const prCommitRefForFile = file.contents_url.split('ref=')[1]
+    const pkgLockNewJson = await getLargeJsonAtRef(
+      client,
+      github.context.repo.owner,
+      github.context.repo.repo,
+      file.filename,
+      prCommitRefForFile,
+    )
+    const pkgLockOldJson = await getLargeJsonAtRef(
+      client,
+      github.context.repo.owner,
+      github.context.repo.repo,
+      file.filename,
+      'master',
+    )
+
+    const oldVesionModuleKey = findKeyEndingWith(
+      pkgLockOldJson.packages,
+      `node_modules/${packageName}`,
+    )
+    const newVesionModuleKey = findKeyEndingWith(
+      pkgLockNewJson.packages,
+      `node_modules/${packageName}`,
+    )
+    let oldVersion = pkgLockOldJson.packages[oldVesionModuleKey].version
+    let newVersion = pkgLockNewJson.packages[newVesionModuleKey].version
+
+    const oldVesionModuleKeyParent = findKeyEndingWith(
+      pkgLockOldJson.packages,
+      `node_modules/${packageParentName}`,
+    )
+    const newVesionModuleKeyParent = findKeyEndingWith(
+      pkgLockNewJson.packages,
+      `node_modules/${packageParentName}`,
+    )
+    const oldVersionParent =
+      pkgLockOldJson.packages[oldVesionModuleKeyParent].dependencies[
+        packageName
+      ].substring(1)
+    const newVersionParent =
+      pkgLockNewJson.packages[newVesionModuleKeyParent].dependencies[
+        packageName
+      ].substring(1)
+
+    // if parent dependency is higher version then existing
+    // npm install will retrive the newer version from the parent dependency
+    if (oldVersionParent > oldVersion) {
+      oldVersion = oldVersionParent
+    }
+    if (newVersionParent > newVersion) {
+      newVersion = newVersionParent
+    }
+    core.info(`oldVersion=${oldVersion}`)
+    core.info(`newVersion=${newVersion}`)
+
+    if (newVersion !== oldVersion) {
+      const pkgChangedFiles = await getChangedFilesBetweenTags(
+        client,
+        'cloud-annotations',
+        'docusaurus-openapi',
+        `v${oldVersion}`,
+        `v${newVersion}`,
+      )
+      const changedComponents = overideComponents.filter(
+        componenet =>
+          pkgChangedFiles.filter(
+            path =>
+              path.includes('docusaurus-theme-openapi/src/theme') &&
+              path.includes(componenet),
+          ).length > 0,
+      )
+      const versionReport = `<tbody><tr><td> Old version </td><td> ${oldVersion} </td></tr>
+      <tr><td> New version </td><td> ${newVersion} </td></tr>
+      `
+      const changedComponentsReport = `<tr><td> Overide components changed </td><td> ${changedComponents.join(
+        ', ',
+      )} </td></tr></tbody></table>
+      `
+      const body = messageTemplate + versionReport + changedComponentsReport
+      await client.rest.issues.createComment({
+        owner: github.context.repo.owner,
+        repo: github.context.repo.repo,
+        issue_number: pr.number,
+        body,
+      })
+
+      core.info('Found changes and posted comment, done.')
+      return
+    }
+
+    core.info('No changes found, done.')
+  } catch (error) {
+    core.setFailed(error.message)
+  }
+}
+
+run()

.github/actions/docusaurus-swizzled-warning/package-lock.json

@@ -0,0 +1,237 @@
+{
+    "name": "docusaurus-swizzled-warning",
+    "version": "0.0.0",
+    "lockfileVersion": 3,
+    "requires": true,
+    "packages": {
+        "": {
+            "name": "docusaurus-swizzled-warning",
+            "version": "0.0.0",
+            "license": "CC0",
+            "dependencies": {
+                "@actions/core": "^1.10.1",
+                "@actions/github": "^6.0.0"
+            }
+        },
+        "node_modules/@actions/core": {
+            "version": "1.10.1",
+            "resolved": "https://registry.npmjs.org/@actions/core/-/core-1.10.1.tgz",
+            "integrity": "sha512-3lBR9EDAY+iYIpTnTIXmWcNbX3T2kCkAEQGIQx4NVQ0575nk2k3GRZDTPQG+vVtS2izSLmINlxXf0uLtnrTP+g==",
+            "dependencies": {
+                "@actions/http-client": "^2.0.1",
+                "uuid": "^8.3.2"
+            }
+        },
+        "node_modules/@actions/github": {
+            "version": "6.0.0",
+            "resolved": "https://registry.npmjs.org/@actions/github/-/github-6.0.0.tgz",
+            "integrity": "sha512-alScpSVnYmjNEXboZjarjukQEzgCRmjMv6Xj47fsdnqGS73bjJNDpiiXmp8jr0UZLdUB6d9jW63IcmddUP+l0g==",
+            "dependencies": {
+                "@actions/http-client": "^2.2.0",
+                "@octokit/core": "^5.0.1",
+                "@octokit/plugin-paginate-rest": "^9.0.0",
+                "@octokit/plugin-rest-endpoint-methods": "^10.0.0"
+            }
+        },
+        "node_modules/@actions/http-client": {
+            "version": "2.2.0",
+            "resolved": "https://registry.npmjs.org/@actions/http-client/-/http-client-2.2.0.tgz",
+            "integrity": "sha512-q+epW0trjVUUHboliPb4UF9g2msf+w61b32tAkFEwL/IwP0DQWgbCMM0Hbe3e3WXSKz5VcUXbzJQgy8Hkra/Lg==",
+            "dependencies": {
+                "tunnel": "^0.0.6",
+                "undici": "^5.25.4"
+            }
+        },
+        "node_modules/@fastify/busboy": {
+            "version": "2.0.0",
+            "resolved": "https://registry.npmjs.org/@fastify/busboy/-/busboy-2.0.0.tgz",
+            "integrity": "sha512-JUFJad5lv7jxj926GPgymrWQxxjPYuJNiNjNMzqT+HiuP6Vl3dk5xzG+8sTX96np0ZAluvaMzPsjhHZ5rNuNQQ==",
+            "engines": {
+                "node": ">=14"
+            }
+        },
+        "node_modules/@octokit/auth-token": {
+            "version": "4.0.0",
+            "resolved": "https://registry.npmjs.org/@octokit/auth-token/-/auth-token-4.0.0.tgz",
+            "integrity": "sha512-tY/msAuJo6ARbK6SPIxZrPBms3xPbfwBrulZe0Wtr/DIY9lje2HeV1uoebShn6mx7SjCHif6EjMvoREj+gZ+SA==",
+            "engines": {
+                "node": ">= 18"
+            }
+        },
+        "node_modules/@octokit/core": {
+            "version": "5.0.1",
+            "resolved": "https://registry.npmjs.org/@octokit/core/-/core-5.0.1.tgz",
+            "integrity": "sha512-lyeeeZyESFo+ffI801SaBKmCfsvarO+dgV8/0gD8u1d87clbEdWsP5yC+dSj3zLhb2eIf5SJrn6vDz9AheETHw==",
+            "dependencies": {
+                "@octokit/auth-token": "^4.0.0",
+                "@octokit/graphql": "^7.0.0",
+                "@octokit/request": "^8.0.2",
+                "@octokit/request-error": "^5.0.0",
+                "@octokit/types": "^12.0.0",
+                "before-after-hook": "^2.2.0",
+                "universal-user-agent": "^6.0.0"
+            },
+            "engines": {
+                "node": ">= 18"
+            }
+        },
+        "node_modules/@octokit/endpoint": {
+            "version": "9.0.1",
+            "resolved": "https://registry.npmjs.org/@octokit/endpoint/-/endpoint-9.0.1.tgz",
+            "integrity": "sha512-hRlOKAovtINHQPYHZlfyFwaM8OyetxeoC81lAkBy34uLb8exrZB50SQdeW3EROqiY9G9yxQTpp5OHTV54QD+vA==",
+            "dependencies": {
+                "@octokit/types": "^12.0.0",
+                "is-plain-object": "^5.0.0",
+                "universal-user-agent": "^6.0.0"
+            },
+            "engines": {
+                "node": ">= 18"
+            }
+        },
+        "node_modules/@octokit/graphql": {
+            "version": "7.0.2",
+            "resolved": "https://registry.npmjs.org/@octokit/graphql/-/graphql-7.0.2.tgz",
+            "integrity": "sha512-OJ2iGMtj5Tg3s6RaXH22cJcxXRi7Y3EBqbHTBRq+PQAqfaS8f/236fUrWhfSn8P4jovyzqucxme7/vWSSZBX2Q==",
+            "dependencies": {
+                "@octokit/request": "^8.0.1",
+                "@octokit/types": "^12.0.0",
+                "universal-user-agent": "^6.0.0"
+            },
+            "engines": {
+                "node": ">= 18"
+            }
+        },
+        "node_modules/@octokit/openapi-types": {
+            "version": "19.0.0",
+            "resolved": "https://registry.npmjs.org/@octokit/openapi-types/-/openapi-types-19.0.0.tgz",
+            "integrity": "sha512-PclQ6JGMTE9iUStpzMkwLCISFn/wDeRjkZFIKALpvJQNBGwDoYYi2fFvuHwssoQ1rXI5mfh6jgTgWuddeUzfWw=="
+        },
+        "node_modules/@octokit/plugin-paginate-rest": {
+            "version": "9.0.0",
+            "resolved": "https://registry.npmjs.org/@octokit/plugin-paginate-rest/-/plugin-paginate-rest-9.0.0.tgz",
+            "integrity": "sha512-oIJzCpttmBTlEhBmRvb+b9rlnGpmFgDtZ0bB6nq39qIod6A5DP+7RkVLMOixIgRCYSHDTeayWqmiJ2SZ6xgfdw==",
+            "dependencies": {
+                "@octokit/types": "^12.0.0"
+            },
+            "engines": {
+                "node": ">= 18"
+            },
+            "peerDependencies": {
+                "@octokit/core": ">=5"
+            }
+        },
+        "node_modules/@octokit/plugin-rest-endpoint-methods": {
+            "version": "10.0.1",
+            "resolved": "https://registry.npmjs.org/@octokit/plugin-rest-endpoint-methods/-/plugin-rest-endpoint-methods-10.0.1.tgz",
+            "integrity": "sha512-fgS6HPkPvJiz8CCliewLyym9qAx0RZ/LKh3sATaPfM41y/O2wQ4Z9MrdYeGPVh04wYmHFmWiGlKPC7jWVtZXQA==",
+            "dependencies": {
+                "@octokit/types": "^12.0.0"
+            },
+            "engines": {
+                "node": ">= 18"
+            },
+            "peerDependencies": {
+                "@octokit/core": ">=5"
+            }
+        },
+        "node_modules/@octokit/request": {
+            "version": "8.1.4",
+            "resolved": "https://registry.npmjs.org/@octokit/request/-/request-8.1.4.tgz",
+            "integrity": "sha512-M0aaFfpGPEKrg7XoA/gwgRvc9MSXHRO2Ioki1qrPDbl1e9YhjIwVoHE7HIKmv/m3idzldj//xBujcFNqGX6ENA==",
+            "dependencies": {
+                "@octokit/endpoint": "^9.0.0",
+                "@octokit/request-error": "^5.0.0",
+                "@octokit/types": "^12.0.0",
+                "is-plain-object": "^5.0.0",
+                "universal-user-agent": "^6.0.0"
+            },
+            "engines": {
+                "node": ">= 18"
+            }
+        },
+        "node_modules/@octokit/request-error": {
+            "version": "5.0.1",
+            "resolved": "https://registry.npmjs.org/@octokit/request-error/-/request-error-5.0.1.tgz",
+            "integrity": "sha512-X7pnyTMV7MgtGmiXBwmO6M5kIPrntOXdyKZLigNfQWSEQzVxR4a4vo49vJjTWX70mPndj8KhfT4Dx+2Ng3vnBQ==",
+            "dependencies": {
+                "@octokit/types": "^12.0.0",
+                "deprecation": "^2.0.0",
+                "once": "^1.4.0"
+            },
+            "engines": {
+                "node": ">= 18"
+            }
+        },
+        "node_modules/@octokit/types": {
+            "version": "12.0.0",
+            "resolved": "https://registry.npmjs.org/@octokit/types/-/types-12.0.0.tgz",
+            "integrity": "sha512-EzD434aHTFifGudYAygnFlS1Tl6KhbTynEWELQXIbTY8Msvb5nEqTZIm7sbPEt4mQYLZwu3zPKVdeIrw0g7ovg==",
+            "dependencies": {
+                "@octokit/openapi-types": "^19.0.0"
+            }
+        },
+        "node_modules/before-after-hook": {
+            "version": "2.2.3",
+            "resolved": "https://registry.npmjs.org/before-after-hook/-/before-after-hook-2.2.3.tgz",
+            "integrity": "sha512-NzUnlZexiaH/46WDhANlyR2bXRopNg4F/zuSA3OpZnllCUgRaOF2znDioDWrmbNVsuZk6l9pMquQB38cfBZwkQ=="
+        },
+        "node_modules/deprecation": {
+            "version": "2.3.1",
+            "resolved": "https://registry.npmjs.org/deprecation/-/deprecation-2.3.1.tgz",
+            "integrity": "sha512-xmHIy4F3scKVwMsQ4WnVaS8bHOx0DmVwRywosKhaILI0ywMDWPtBSku2HNxRvF7jtwDRsoEwYQSfbxj8b7RlJQ=="
+        },
+        "node_modules/is-plain-object": {
+            "version": "5.0.0",
+            "resolved": "https://registry.npmjs.org/is-plain-object/-/is-plain-object-5.0.0.tgz",
+            "integrity": "sha512-VRSzKkbMm5jMDoKLbltAkFQ5Qr7VDiTFGXxYFXXowVj387GeGNOCsOH6Msy00SGZ3Fp84b1Naa1psqgcCIEP5Q==",
+            "engines": {
+                "node": ">=0.10.0"
+            }
+        },
+        "node_modules/once": {
+            "version": "1.4.0",
+            "resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz",
+            "integrity": "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==",
+            "dependencies": {
+                "wrappy": "1"
+            }
+        },
+        "node_modules/tunnel": {
+            "version": "0.0.6",
+            "resolved": "https://registry.npmjs.org/tunnel/-/tunnel-0.0.6.tgz",
+            "integrity": "sha512-1h/Lnq9yajKY2PEbBadPXj3VxsDDu844OnaAo52UVmIzIvwwtBPIuNvkjuzBlTWpfJyUbG3ez0KSBibQkj4ojg==",
+            "engines": {
+                "node": ">=0.6.11 <=0.7.0 || >=0.7.3"
+            }
+        },
+        "node_modules/undici": {
+            "version": "5.26.3",
+            "resolved": "https://registry.npmjs.org/undici/-/undici-5.26.3.tgz",
+            "integrity": "sha512-H7n2zmKEWgOllKkIUkLvFmsJQj062lSm3uA4EYApG8gLuiOM0/go9bIoC3HVaSnfg4xunowDE2i9p8drkXuvDw==",
+            "dependencies": {
+                "@fastify/busboy": "^2.0.0"
+            },
+            "engines": {
+                "node": ">=14.0"
+            }
+        },
+        "node_modules/universal-user-agent": {
+            "version": "6.0.0",
+            "resolved": "https://registry.npmjs.org/universal-user-agent/-/universal-user-agent-6.0.0.tgz",
+            "integrity": "sha512-isyNax3wXoKaulPDZWHQqbmIx1k2tb9fb3GGDBRxCscfYV2Ch7WxPArBsFEG8s/safwXTT7H4QGhaIkTp9447w=="
+        },
+        "node_modules/uuid": {
+            "version": "8.3.2",
+            "resolved": "https://registry.npmjs.org/uuid/-/uuid-8.3.2.tgz",
+            "integrity": "sha512-+NYs2QeMWy+GWFOEm9xnn6HCDp0l7QBD7ml8zLUmJ+93Q5NF0NocErnwkTkXVFNiX3/fpC6afS8Dhb/gz7R7eg==",
+            "bin": {
+                "uuid": "dist/bin/uuid"
+            }
+        },
+        "node_modules/wrappy": {
+            "version": "1.0.2",
+            "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz",
+            "integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ=="
+        }
+    }
+}

.github/actions/docusaurus-swizzled-warning/package.json

@@ -0,0 +1,16 @@
+{
+    "name": "docusaurus-swizzled-warning",
+    "version": "0.0.0",
+    "description": "",
+    "main": "index.js",
+    "private": true,
+    "scripts": {
+        "test": "echo \"Error: no test specified\" && exit 1"
+    },
+    "author": "jNullj",
+    "license": "CC0",
+    "dependencies": {
+        "@actions/core": "^1.10.1",
+        "@actions/github": "^6.0.0"
+    }
+}

.github/actions/draft-release/Dockerfile

@@ -1,4 +1,4 @@
-FROM node:18-bullseye
+FROM node:20-bullseye
 
 RUN apt-get update
 RUN apt-get install -y jq

.github/actions/service-tests/action.yml

@@ -16,6 +16,10 @@ inputs:
     description: 'The SERVICETESTS_OBS_PASS secret'
     required: false
     default: ''
+  pepy-key:
+    description: 'The SERVICETESTS_PEPY_KEY secret'
+    required: false
+    default: ''
   sl-insight-user-uuid:
     description: 'The SERVICETESTS_SL_INSIGHT_USER_UUID secret'
     required: false
@@ -66,6 +70,7 @@ runs:
         LIBRARIESIO_TOKENS: '${{ inputs.librariesio-tokens }}'
         OBS_USER: '${{ inputs.obs-user }}'
         OBS_PASS: '${{ inputs.obs-pass }}'
+        PEPY_KEY: '${{ inputs.pepy-key }}'
         SL_INSIGHT_USER_UUID: '${{ inputs.sl-insight-user-uuid }}'
         SL_INSIGHT_API_TOKEN: '${{ inputs.sl-insight-api-token }}'
         TWITCH_CLIENT_ID: '${{ inputs.twitch-client-id }}'

.github/actions/setup/action.yml

@@ -2,8 +2,12 @@ name: 'Set up project'
 description: 'Set up project'
 inputs:
   node-version:
-    description: 'Version Spec of the version to use. Examples: 12.x, 10.15.1, >=10.15.0.'
+    description: 'Version Spec of the node version to use. Examples: 12.x, 10.15.1, >=10.15.0.'
     required: true
+  npm-version:
+    description: 'Version Spec of the npm version to use. Examples: 9.x, 10.2.3, >=10.1.0.'
+    required: false
+    default: '^10'
   cypress:
     description: 'Install Cypress binary (boolean)'
     type: boolean
@@ -19,8 +23,8 @@ runs:
       with:
         node-version: ${{ inputs.node-version }}
 
-    - name: Install NPM 9
-      run: npm install -g npm@^9.0.0
+    - name: Install NPM ${{ inputs.npm-version }}
+      run: npm install -g npm@${{ inputs.npm-version }}
       shell: bash
 
     - name: Install dependencies

.github/dependabot.yml

@@ -17,9 +17,6 @@ updates:
       - dependency-name: 'decamelize'
       - dependency-name: 'humanize-string'
 
-      # https://github.com/badges/shields/pull/7288#issuecomment-974699240
-      - dependency-name: '@types/node'
-
   # badge-maker package dependencies
   - package-ecosystem: npm
     directory: '/badge-maker'
@@ -30,16 +27,6 @@ updates:
     open-pull-requests-limit: 99
     rebase-strategy: disabled
 
-  # close-bot package dependencies
-  - package-ecosystem: npm
-    directory: '/.github/actions/close-bot'
-    schedule:
-      interval: weekly
-      day: friday
-      time: '12:00'
-    open-pull-requests-limit: 99
-    rebase-strategy: disabled
-
   # GH actions
   - package-ecosystem: 'github-actions'
     directory: '/'
@@ -47,3 +34,13 @@ updates:
       interval: weekly
     open-pull-requests-limit: 99
     rebase-strategy: disabled
+
+    # docusaurus-swizzled-warning package dependencies
+  - package-ecosystem: npm
+    directory: '/.github/actions/docusaurus-swizzled-warning'
+    schedule:
+      interval: weekly
+      day: friday
+      time: '12:00'
+    open-pull-requests-limit: 99
+    rebase-strategy: disabled

.github/scripts/check-docusaurus-versions.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+
+set -euo pipefail
+
+# Docusaurus outputs some important errors as log messages
+# but doesn't actually fail
+# https://github.com/facebook/docusaurus/blob/v2.4.3/packages/docusaurus/src/server/siteMetadata.ts#L75-L92
+# this script runs `docusaurus build`. If it outputs any [ERROR]s, we exit with 1
+
+if ( npm run build 2>&1 | grep '\[ERROR\]' )
+then
+    echo "You probably need to run: npm update @docusaurus/preset-classic"
+    exit 1
+else
+    exit 0
+fi

.github/scripts/deploy-review-app.sh

@@ -18,12 +18,13 @@ git checkout "pr-$PR_NUMBER"
 
 # If the app does not already exist, create it
 if ! flyctl status --app "$app"; then
-  flyctl launch --no-deploy --copy-config --name "$app" --region "$region" --org "$org"
+  flyctl launch --no-deploy --copy-config --name "$app" --region "$region" --org "$org" --dockerfile ./Dockerfile
   echo $SECRETS | tr " " "\n" | flyctl secrets import --app "$app"
 fi
 
 # Deploy
 flyctl deploy --app "$app" --region "$region"
+flyctl scale count 1 --app "$app" --yes
 
 # Post a comment on the PR
 app_url=$(flyctl status --app "$app" --json | jq -r .Hostname)

.github/workflows/build-docker-image.yml

@@ -10,10 +10,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v2
+        uses: docker/setup-buildx-action@v3
         with:
           version: v0.9.1
 
@@ -21,7 +21,7 @@ jobs:
         run: echo "SHORT_SHA=${GITHUB_SHA::7}" >> $GITHUB_ENV
 
       - name: Build
-        uses: docker/build-push-action@v4
+        uses: docker/build-push-action@v5
         with:
           context: .
           push: false

.github/workflows/check-docusaurus-versions.yml

@@ -0,0 +1,23 @@
+name: Check Docusaurus Plugin Versions
+on:
+  pull_request:
+    types: [opened, reopened, synchronize]
+  push:
+    branches-ignore:
+      - 'gh-pages'
+      - 'dependabot/**'
+
+jobs:
+  check-docusaurus-versions:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup
+        uses: ./.github/actions/setup
+        with:
+          node-version: 20
+          cypress: true
+
+      - run: .github/scripts/check-docusaurus-versions.sh

.github/workflows/cleanup-review-apps.yml

@@ -10,7 +10,7 @@ jobs:
     runs-on: ubuntu-latest
     environment: 'Review Apps'
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: superfly/flyctl-actions/setup-flyctl@master
 
       - name: install jq

.github/workflows/create-release.yml

@@ -24,7 +24,7 @@ jobs:
         run: echo "::set-output name=date::$(date --rfc-3339=date)"
 
       - name: Checkout branch "master"
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           ref: 'master'
 
@@ -35,18 +35,18 @@ jobs:
           tag: server-${{ steps.date.outputs.date }}
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v2
+        uses: docker/setup-buildx-action@v3
         with:
           version: v0.9.1
 
       - name: Login to DockerHub
-        uses: docker/login-action@v2
+        uses: docker/login-action@v3
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
       - name: Build and push snapshot release to DockerHub
-        uses: docker/build-push-action@v4
+        uses: docker/build-push-action@v5
         with:
           context: .
           push: true
@@ -55,14 +55,14 @@ jobs:
             version=server-${{ steps.date.outputs.date }}
 
       - name: Login to GHCR
-        uses: docker/login-action@v2
+        uses: docker/login-action@v3
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Build and push snapshot release to GHCR
-        uses: docker/build-push-action@v4
+        uses: docker/build-push-action@v5
         with:
           context: .
           push: true

.github/workflows/danger.yml

@@ -14,12 +14,12 @@ jobs:
     if: github.actor != 'dependabot[bot]' && github.actor != 'repo-ranger[bot]'
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Setup
         uses: ./.github/actions/setup
         with:
-          node-version: 16
+          node-version: 20
 
       - name: Danger
         run: npm run danger ci

.github/workflows/deploy-docs.yml

@@ -12,14 +12,14 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           persist-credentials: false
 
       - name: Setup
         uses: ./.github/actions/setup
         with:
-          node-version: 16
+          node-version: 20
 
       - name: Build
         run: npm run build-docs

.github/workflows/deploy-review-app.yml

@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-latest
     environment: 'Review Apps'
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           fetch-depth: 0
       - uses: superfly/flyctl-actions/setup-flyctl@master
@@ -35,6 +35,7 @@ jobs:
             LIBRARIESIO_TOKENS=${{ secrets.SERVICETESTS_LIBRARIESIO_TOKENS }}
             OBS_USER=${{ secrets.SERVICETESTS_OBS_USER }}
             OBS_PASS=${{ secrets.SERVICETESTS_OBS_PASS }}
+            PEPY_KEY=${{ secrets.SERVICETESTS_PEPY_KEY }}
             SL_INSIGHT_API_TOKEN=${{ secrets.SERVICETESTS_SL_INSIGHT_USER_UUID }}
             SL_INSIGHT_USER_UUID=${{ secrets.SERVICETESTS_SL_INSIGHT_API_TOKEN }}
             TWITCH_CLIENT_ID=${{ secrets.SERVICETESTS_TWITCH_CLIENT_ID }}

.github/workflows/docusaurus-swizzled-warning.yml

@@ -1,22 +1,22 @@
-name: Auto close
+name: Docusaurus swizzled component changes warning
 on:
-  pull_request_target:
+  pull_request:
     types: [opened]
 
 permissions:
   pull-requests: write
 
 jobs:
-  auto-close:
+  docusaurus-swizzled-warning:
     runs-on: ubuntu-latest
     if: github.actor == 'dependabot[bot]'
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Install action dependencies
-        run: cd .github/actions/close-bot && npm ci
+        run: cd .github/actions/docusaurus-swizzled-warning && npm ci
 
-      - uses: ./.github/actions/close-bot
+      - uses: ./.github/actions/docusaurus-swizzled-warning
         with:
           github-token: '${{ secrets.GITHUB_TOKEN }}'

.github/workflows/draft-release.yml

@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Draft Release
         uses: ./.github/actions/draft-release

.github/workflows/enforce-dependency-review.yml

@@ -8,6 +8,6 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: 'Checkout Repository'
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: 'Dependency Review'
         uses: actions/dependency-review-action@v3

.github/workflows/publish-docker-next.yml

@@ -12,15 +12,15 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v2
+        uses: docker/setup-buildx-action@v3
         with:
           version: v0.9.1
 
       - name: Login to DockerHub
-        uses: docker/login-action@v2
+        uses: docker/login-action@v3
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
@@ -29,7 +29,8 @@ jobs:
         run: echo "SHORT_SHA=${GITHUB_SHA::7}" >> $GITHUB_ENV
 
       - name: Build and push to DockerHub
-        uses: docker/build-push-action@v4
+        id: docker_build_push
+        uses: docker/build-push-action@v5
         with:
           context: .
           push: true
@@ -37,15 +38,18 @@ jobs:
           build-args: |
             version=${{ env.SHORT_SHA }}
 
+      - name: Output Image Digest
+        run: echo ${{ steps.docker_build_push.outputs.digest }} >> $GITHUB_STEP_SUMMARY
+
       - name: Login to GHCR
-        uses: docker/login-action@v2
+        uses: docker/login-action@v3
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Build and push to GHCR
-        uses: docker/build-push-action@v4
+        uses: docker/build-push-action@v5
         with:
           context: .
           push: true

.github/workflows/test-bug-run-badge.yml

@@ -13,9 +13,11 @@ jobs:
     steps:
       - name: Test badge test run conditions
         id: testCondition
+        env:
+          ISSUE_BODY: '${{ github.event.issue.body }}'
         run: |
-          product=$(echo "${{ github.event.issue.body }}" | grep -A2 "Are you experiencing an issue with.*" | tail -n 1)
-          link=$(echo "${{ github.event.issue.body }}" | grep -A2 "Link to the badge.*" | tail -n 1)
+          product=$(echo "$ISSUE_BODY" | grep -A2 "Are you experiencing an issue with.*" | tail -n 1)
+          link=$(echo "$ISSUE_BODY" | grep -A2 "Link to the badge.*" | tail -n 1)
 
           if [[ "$product" == "shields.io" && "$link" == "https://img.shields.io"* ]]; then
             echo "runNext=true" >> "$GITHUB_OUTPUT"
@@ -33,12 +35,12 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Setup
         uses: ./.github/actions/setup
         with:
-          node-version: 16
+          node-version: 20
           cypress: false
 
       - name: Output debug info
@@ -47,7 +49,7 @@ jobs:
         run: npm run badge $TEST_BADGE_LINK
 
       - name: Add Comment to Issue
-        uses: actions/github-script@v6
+        uses: actions/github-script@v7
         with:
           script: |
             const issueNumber = context.issue.number;

.github/workflows/test-e2e.yml

@@ -12,7 +12,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Cache Cypress binary
         id: cache-cypress
@@ -26,7 +26,7 @@ jobs:
       - name: Setup
         uses: ./.github/actions/setup
         with:
-          node-version: 16
+          node-version: 20
           cypress: true
 
       - name: Run tests
@@ -36,14 +36,14 @@ jobs:
 
       - name: Archive videos
         if: always()
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: videos
           path: cypress/videos
 
       - name: Archive screenshots
         if: always()
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: screenshots
           path: cypress/screenshots

.github/workflows/test-integration-21.yml

@@ -1,4 +1,4 @@
-name: Integration@node 18
+name: Integration@node 21
 on:
   pull_request:
     types: [opened, reopened, synchronize]
@@ -8,7 +8,7 @@ on:
       - 'dependabot/**'
 
 jobs:
-  test-integration-18:
+  test-integration-21:
     runs-on: ubuntu-latest
     env:
       PAT_EXISTS: ${{ secrets.GH_PAT != '' }}
@@ -30,12 +30,12 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Setup
         uses: ./.github/actions/setup
         with:
-          node-version: 18
+          node-version: 21
         env:
           NPM_CONFIG_ENGINE_STRICT: 'false'
 

.github/workflows/test-integration.yml

@@ -30,12 +30,12 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Setup
         uses: ./.github/actions/setup
         with:
-          node-version: 16
+          node-version: 20
 
       - name: Integration Tests (with PAT)
         if: ${{ env.PAT_EXISTS == 'true' }}

.github/workflows/test-lint.yml

@@ -12,12 +12,12 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Setup
         uses: ./.github/actions/setup
         with:
-          node-version: 16
+          node-version: 20
 
       - name: ESLint
         if: always()

.github/workflows/test-main-21.yml

@@ -1,4 +1,4 @@
-name: Main@node 18
+name: Main@node 21
 on:
   pull_request:
     types: [opened, reopened, synchronize]
@@ -8,16 +8,16 @@ on:
       - 'dependabot/**'
 
 jobs:
-  test-main-18:
+  test-main-21:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Setup
         uses: ./.github/actions/setup
         with:
-          node-version: 18
+          node-version: 21
         env:
           NPM_CONFIG_ENGINE_STRICT: 'false'
 

.github/workflows/test-main.yml

@@ -17,12 +17,12 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Setup
         uses: ./.github/actions/setup
         with:
-          node-version: 16
+          node-version: 20
 
       - name: Core tests
         uses: ./.github/actions/core-tests

.github/workflows/test-package-cli.yml

@@ -21,10 +21,10 @@ jobs:
           - node: '20'
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Install Node JS ${{ inputs.node-version }}
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node }}
 

.github/workflows/test-package-lib.yml

@@ -14,19 +14,23 @@ jobs:
       matrix:
         include:
           - node: '16'
-            engine-strict: 'true'
+            npm: '^9'
+            engine-strict: 'false'
           - node: '18'
+            npm: '^9'
             engine-strict: 'false'
           - node: '20'
-            engine-strict: 'false'
+            npm: '^10'
+            engine-strict: 'true'
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Setup
         uses: ./.github/actions/setup
         with:
           node-version: ${{ matrix.node }}
+          npm-version: ${{ matrix.npm }}
         env:
           NPM_CONFIG_ENGINE_STRICT: ${{ matrix.engine-strict }}
 

.github/workflows/test-services-21.yml

@@ -1,4 +1,4 @@
-name: Services@node 18
+name: Services@node 21
 on:
   pull_request:
     types: [opened, edited, reopened, synchronize]
@@ -7,17 +7,17 @@ on:
       - 'gh-readonly-queue/**'
 
 jobs:
-  test-services-18:
+  test-services-21:
     runs-on: ubuntu-latest
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Setup
         uses: ./.github/actions/setup
         with:
-          node-version: 18
+          node-version: 21
         env:
           NPM_CONFIG_ENGINE_STRICT: 'false'
 
@@ -29,6 +29,7 @@ jobs:
           librariesio-tokens: '${{ secrets.SERVICETESTS_LIBRARIESIO_TOKENS }}'
           obs-user: '${{ secrets.SERVICETESTS_OBS_USER }}'
           obs-pass: '${{ secrets.SERVICETESTS_OBS_PASS }}'
+          pepy-key: '${{ secrets.SERVICETESTS_PEPY_KEY }}'
           sl-insight-user-uuid: '${{ secrets.SERVICETESTS_SL_INSIGHT_USER_UUID }}'
           sl-insight-api-token: '${{ secrets.SERVICETESTS_SL_INSIGHT_API_TOKEN }}'
           twitch-client-id: '${{ secrets.SERVICETESTS_TWITCH_CLIENT_ID }}'

.github/workflows/test-services.yml

@@ -12,12 +12,12 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Setup
         uses: ./.github/actions/setup
         with:
-          node-version: 16
+          node-version: 20
 
       - name: Service tests (triggered from local branch)
         if: github.event.pull_request.head.repo.full_name == github.repository
@@ -27,6 +27,7 @@ jobs:
           librariesio-tokens: '${{ secrets.SERVICETESTS_LIBRARIESIO_TOKENS }}'
           obs-user: '${{ secrets.SERVICETESTS_OBS_USER }}'
           obs-pass: '${{ secrets.SERVICETESTS_OBS_PASS }}'
+          pepy-key: '${{ secrets.SERVICETESTS_PEPY_KEY }}'
           sl-insight-user-uuid: '${{ secrets.SERVICETESTS_SL_INSIGHT_USER_UUID }}'
           sl-insight-api-token: '${{ secrets.SERVICETESTS_SL_INSIGHT_API_TOKEN }}'
           twitch-client-id: '${{ secrets.SERVICETESTS_TWITCH_CLIENT_ID }}'

.github/workflows/update-github-api.yml

@@ -14,12 +14,12 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Setup
         uses: ./.github/actions/setup
         with:
-          node-version: 16
+          node-version: 20
 
       - name: Check for new GitHub API version
         run: node scripts/update-github-api.js

CHANGELOG.md

@@ -4,6 +4,80 @@ Note: this changelog is for the shields.io server. The changelog for the badge-m
 
 ---
 
+## server-2024-01-01
+
+The most important changes in this release for users hosting their own instance are:
+
+The shields docker image is now based on node 20:
+
+- deploy on node 20 [#9799](https://github.com/badges/shields/issues/9799)
+
+It is now possible to use [authentication for DockerHub](https://github.com/badges/shields/blob/master/doc/server-secrets.md#dockerhub) to allow higher API rate limit or access to private repos:
+
+- call [docker] with auth [#9803](https://github.com/badges/shields/issues/9803)
+
+### New Badges
+
+- [Thunderstore] Add Thunderstore Badges [#9782](https://github.com/badges/shields/issues/9782)
+- Add [Raycast] Badge [#9801](https://github.com/badges/shields/issues/9801)
+- [GITEA] add new gitea service (release/languages) [#9781](https://github.com/badges/shields/issues/9781)
+- Add [NpmStatDownloads] Badge [#9783](https://github.com/badges/shields/issues/9783)
+
+### Frontend Changes
+
+- improve documentation for [dynamicxml] service [#9798](https://github.com/badges/shields/issues/9798)
+- add description to interval enums [#9854](https://github.com/badges/shields/issues/9854)
+- convert 'style' param to enum [#9853](https://github.com/badges/shields/issues/9853)
+- Ensure social category badges are rendered with social style and logo; affects [gitlab keybase lemmy modrinth thunderstore twitch] gist github reddit [#9859](https://github.com/badges/shields/issues/9859)
+
+### Fixes
+
+- [pub] Use official version endpoint for pub-service [#9802](https://github.com/badges/shields/issues/9802)
+- cache weblate badges for longer [#9786](https://github.com/badges/shields/issues/9786)
+- [Discourse] Update schema keys to use plural form (`topic_count` -> `topics_count`) [#9778](https://github.com/badges/shields/issues/9778)
+- cache some badges for longer [#9785](https://github.com/badges/shields/issues/9785)
+- increase page size for github release badge by semver [#9818](https://github.com/badges/shields/issues/9818)
+- Dependency updates
+
+## server-2023-12-04
+
+- move from @renovate/pep440 to @renovatebot/pep440 [#9614](https://github.com/badges/shields/issues/9614)
+- deprecate/fix [ansible] galaxy services [#9648](https://github.com/badges/shields/issues/9648)
+- call [pepy] with auth [#9748](https://github.com/badges/shields/issues/9748)
+- add meaningful descriptions including keywords [#9715](https://github.com/badges/shields/issues/9715)
+- Dependency updates
+
+## server-2023-11-01
+
+- fix greasyfork 404 bug [#9632](https://github.com/badges/shields/issues/9632)
+- Hacktoberfest 2023 support - resolves #9636 [#9637](https://github.com/badges/shields/issues/9637)
+- switch to fixed OpenCollective images [#9615](https://github.com/badges/shields/issues/9615)
+- Dependency updates
+
+## server-2023-10-02
+
+- add python package total downloads from [pepy] badge [#9564](https://github.com/badges/shields/issues/9564)
+- deprecate [redmine] plugin rating badges [#9568](https://github.com/badges/shields/issues/9568)
+- fix [bower] version badge [#9567](https://github.com/badges/shields/issues/9567)
+- Add [PythonVersionFromToml] shield [#9516](https://github.com/badges/shields/issues/9516)
+- Add [dub] score badge service [#9549](https://github.com/badges/shields/issues/9549)
+- Dependency updates
+
+## server-2023-09-04
+
+- Fix [testspace] badges [#9525](https://github.com/badges/shields/issues/9525)
+- fix rSt code example [#9528](https://github.com/badges/shields/issues/9528)
+- Add dynamic TOML support via [DynamicToml] Service [#9517](https://github.com/badges/shields/issues/9517)
+- cache [pypi] downloads for longer [#9522](https://github.com/badges/shields/issues/9522)
+- [twitter] --> x [#9496](https://github.com/badges/shields/issues/9496)
+- [bundlejs] add badge for the npm package size [#9055](https://github.com/badges/shields/issues/9055)
+- Switch [OpenCollective] badges to use GraphQL and auth [#9387](https://github.com/badges/shields/issues/9387)
+- [Pulsar] Add Pulsar Badges for Stargazers & Downloads [#8767](https://github.com/badges/shields/issues/8767)
+- Add [CurseForge] badges [#9252](https://github.com/badges/shields/issues/9252)
+- deploy on node 18 [#9385](https://github.com/badges/shields/issues/9385)
+- allow calling [github] without auth [#9427](https://github.com/badges/shields/issues/9427)
+- Dependency updates
+
 ## server-2023-08-01
 
 - Convert `examples` arrays to `openApi` objects (part 1) [#9320](https://github.com/badges/shields/issues/9320)

Dockerfile

@@ -1,4 +1,4 @@
-FROM node:16-alpine AS Builder
+FROM node:20-alpine AS Builder
 
 RUN mkdir -p /usr/src/app
 RUN mkdir /usr/src/app/private
@@ -15,11 +15,11 @@ RUN NODE_ENV=development CYPRESS_INSTALL_BINARY=0 npm ci
 
 COPY . /usr/src/app
 RUN npm run build
-RUN npm prune --production
+RUN npm prune --omit=dev
 RUN npm cache clean --force
 
 # Use multi-stage build to reduce size
-FROM node:16-alpine
+FROM node:20-alpine
 
 ARG version=dev
 ENV DOCKER_SHIELDS_VERSION=$version

README.md

@@ -22,9 +22,6 @@
     <a href="https://discord.gg/HjJCwm5">
         <img src="https://img.shields.io/discord/308323056592486420?logo=discord"
             alt="chat on Discord"></a>
-    <a href="https://twitter.com/intent/follow?screen_name=shields_io">
-        <img src="https://img.shields.io/twitter/follow/shields_io?style=social&logo=twitter"
-            alt="follow on Twitter"></a>
 </p>
 
 This is home to [Shields.io][shields.io], a service for concise, consistent,
@@ -70,7 +67,7 @@ This repo hosts:
 [Make your own badges!][custom badges]
 (Quick example: `https://img.shields.io/badge/left-right-f39f37`)
 
-[custom badges]: http://localhost:3000/badges/static-badge
+[custom badges]: https://img.shields.io/badges/static-badge
 
 ### Quickstart
 
@@ -92,14 +89,17 @@ You can read a [tutorial on how to add a badge][tutorial].
 
 [![GitHub issues by-label](https://img.shields.io/github/issues/badges/shields/good%20first%20issue)](https://github.com/badges/shields/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
 
+If you intend on reporting or contributing a fix related to security vulnerabilities, please first refer to our [security policy][security].
+
 [service-tests]: https://github.com/badges/shields/blob/master/doc/service-tests.md
 [tutorial]: https://github.com/badges/shields/blob/master/doc/TUTORIAL.md
 [contributing]: https://github.com/badges/shields/blob/master/CONTRIBUTING.md
+[security]: https://github.com/badges/shields/blob/master/SECURITY.md
 
 ## Development
 
-1. Install Node 16 or later. You can use the [package manager][] of your choice.
-   Tests need to pass in Node 16 and 17.
+1. Install Node 20 or later. You can use the [package manager][] of your choice.
+   Tests need to pass in Node 20 and 21.
 2. Clone this repository.
 3. Run `npm ci` to install the dependencies.
 4. Run `npm start` to start the badge server and the frontend dev server.

badge-maker/lib/xml.js

@@ -35,7 +35,7 @@ class XmlElement {
    *    Name of the XML tag
    * @param {Array.<string|module:badge-maker/lib/xml~XmlElement>} [attrs.content=[]]
    *    Array of objects to render inside the tag. content may contain a mix of
-   *    string and XmlElement objects. If content is `[]` or ommitted the
+   *    string and XmlElement objects. If content is `[]` or omitted the
    *    element will be rendered as a self-closing element.
    * @param {object} [attrs.attrs={}]
    *    Object representing the tag's attributes as name/value pairs

config/custom-environment-variables.yml

@@ -77,7 +77,10 @@ private:
   bitbucket_password: 'BITBUCKET_PASS'
   bitbucket_server_username: 'BITBUCKET_SERVER_USER'
   bitbucket_server_password: 'BITBUCKET_SERVER_PASS'
+  curseforge_api_key: 'CURSEFORGE_API_KEY'
   discord_bot_token: 'DISCORD_BOT_TOKEN'
+  dockerhub_username: 'DOCKERHUB_USER'
+  dockerhub_pat: 'DOCKERHUB_PAT'
   drone_token: 'DRONE_TOKEN'
   gh_client_id: 'GH_CLIENT_ID'
   gh_client_secret: 'GH_CLIENT_SECRET'
@@ -94,6 +97,8 @@ private:
   obs_user: 'OBS_USER'
   obs_pass: 'OBS_PASS'
   redis_url: 'REDIS_URL'
+  opencollective_token: 'OPENCOLLECTIVE_TOKEN'
+  pepy_key: 'PEPY_KEY'
   postgres_url: 'POSTGRES_URL'
   sentry_dsn: 'SENTRY_DSN'
   sl_insight_userUuid: 'SL_INSIGHT_USER_UUID'

config/local-shields-io-production.template.yml

@@ -1,5 +1,6 @@
 private:
   # These are the keys which are set on the production servers.
+  curseforge_api_key: ...
   discord_bot_token: ...
   gh_client_id: ...
   gh_client_secret: ...

config/local.template.yml

@@ -4,6 +4,7 @@ private:
   # The possible values are documented in `doc/server-secrets.md`. Note that
   # you can also set these values through environment variables, which may be
   # preferable for self hosting.
+  curseforge_api_key: '...'
   gh_token: '...'
   gitlab_token: '...'
   obs_user: '...'

core/base-service/auth-helper.js

@@ -1,5 +1,13 @@
 import { URL } from 'url'
-import { InvalidParameter } from './errors.js'
+import dayjs from 'dayjs'
+import Joi from 'joi'
+import checkErrorResponse from './check-error-response.js'
+import { InvalidParameter, InvalidResponse } from './errors.js'
+import { fetch } from './got.js'
+import { parseJson } from './json.js'
+import validate from './validate.js'
+
+let jwtCache = Object.create(null)
 
 class AuthHelper {
   constructor(
@@ -87,7 +95,7 @@ class AuthHelper {
     }
   }
 
-  shouldAuthenticateRequest({ url, options = {} }) {
+  isAllowedOrigin(url) {
     let parsed
     try {
       parsed = new URL(url)
@@ -97,7 +105,11 @@ class AuthHelper {
 
     const { protocol, host } = parsed
     const origin = `${protocol}//${host}`
-    const originViolation = !this._authorizedOrigins.includes(origin)
+    return this._authorizedOrigins.includes(origin)
+  }
+
+  shouldAuthenticateRequest({ url, options = {} }) {
+    const originViolation = !this.isAllowedOrigin(url)
 
     const strictSslCheckViolation =
       this._requireStrictSslToAuthenticate &&
@@ -153,6 +165,11 @@ class AuthHelper {
       : undefined
   }
 
+  _apiKeyHeader(apiKeyHeader) {
+    const { _pass: pass } = this
+    return this.isConfigured ? { [apiKeyHeader]: pass } : undefined
+  }
+
   static _mergeHeaders(requestParams, headers) {
     const {
       options: { headers: existingHeaders, ...restOptions } = {},
@@ -170,6 +187,12 @@ class AuthHelper {
     }
   }
 
+  withApiKeyHeader(requestParams, header = 'x-api-key') {
+    return this._withAnyAuth(requestParams, requestParams =>
+      this.constructor._mergeHeaders(requestParams, this._apiKeyHeader(header)),
+    )
+  }
+
   withBearerAuthHeader(
     requestParams,
     bearerKey = 'Bearer', // lgtm [js/hardcoded-credentials]
@@ -207,6 +230,103 @@ class AuthHelper {
       }),
     )
   }
+
+  static _getJwtExpiry(token, max = dayjs().add(1, 'hours').unix()) {
+    // get the expiry timestamp for this JWT (capped at a max length)
+    const parts = token.split('.')
+
+    if (parts.length < 2) {
+      throw new InvalidResponse({
+        prettyMessage: 'invalid response data from auth endpoint',
+      })
+    }
+
+    const json = validate(
+      {
+        ErrorClass: InvalidResponse,
+        prettyErrorMessage: 'invalid response data from auth endpoint',
+      },
+      parseJson(Buffer.from(parts[1], 'base64').toString()),
+      Joi.object({ exp: Joi.number().required() }).required(),
+    )
+
+    return Math.min(json.exp, max)
+  }
+
+  static _isJwtValid(expiry) {
+    // we consider the token valid if the expiry
+    // datetime is later than (now + 1 minute)
+    return dayjs.unix(expiry).isAfter(dayjs().add(1, 'minutes'))
+  }
+
+  async _getJwt(loginEndpoint) {
+    const { _user: username, _pass: password } = this
+
+    // attempt to get JWT from cache
+    if (
+      jwtCache?.[loginEndpoint]?.[username]?.token &&
+      jwtCache?.[loginEndpoint]?.[username]?.expiry &&
+      this.constructor._isJwtValid(jwtCache[loginEndpoint][username].expiry)
+    ) {
+      // cache hit
+      return jwtCache[loginEndpoint][username].token
+    }
+
+    // cache miss - request a new JWT
+    const originViolation = !this.isAllowedOrigin(loginEndpoint)
+    if (originViolation) {
+      throw new InvalidParameter({
+        prettyMessage: 'requested origin not authorized',
+      })
+    }
+
+    const { buffer } = await checkErrorResponse({})(
+      await fetch(loginEndpoint, {
+        method: 'POST',
+        form: { username, password },
+      }),
+    )
+
+    const json = validate(
+      {
+        ErrorClass: InvalidResponse,
+        prettyErrorMessage: 'invalid response data from auth endpoint',
+      },
+      parseJson(buffer),
+      Joi.object({ token: Joi.string().required() }).required(),
+    )
+
+    const token = json.token
+    const expiry = this.constructor._getJwtExpiry(token)
+
+    // store in the cache
+    if (!(loginEndpoint in jwtCache)) {
+      jwtCache[loginEndpoint] = {}
+    }
+    jwtCache[loginEndpoint][username] = { token, expiry }
+
+    return token
+  }
+
+  async _getJwtAuthHeader(loginEndpoint) {
+    if (!this.isConfigured) {
+      return undefined
+    }
+
+    const token = await this._getJwt(loginEndpoint)
+    return { Authorization: `Bearer ${token}` }
+  }
+
+  async withJwtAuth(requestParams, loginEndpoint) {
+    const authHeader = await this._getJwtAuthHeader(loginEndpoint)
+    return this._withAnyAuth(requestParams, requestParams =>
+      this.constructor._mergeHeaders(requestParams, authHeader),
+    )
+  }
 }
 
-export { AuthHelper }
+function clearJwtCache() {
+  jwtCache = Object.create(null)
+}
+
+export { AuthHelper, clearJwtCache }

core/base-service/auth-helper.spec.js

@@ -1,7 +1,32 @@
+import dayjs from 'dayjs'
+import nock from 'nock'
 import { expect } from 'chai'
 import { test, given, forCases } from 'sazerac'
-import { AuthHelper } from './auth-helper.js'
-import { InvalidParameter } from './errors.js'
+import { AuthHelper, clearJwtCache } from './auth-helper.js'
+import { InvalidParameter, InvalidResponse } from './errors.js'
+
+function base64UrlEncode(input) {
+  const base64 = btoa(JSON.stringify(input))
+  return base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+}
+
+function getMockJwt(extras) {
+  // this function returns a mock JWT that contains enough
+  // for a unit test but ignores important aspects e.g: signing
+
+  const header = {
+    alg: 'HS256',
+    typ: 'JWT',
+  }
+  const payload = {
+    iat: Math.floor(Date.now() / 1000),
+    ...extras,
+  }
+
+  const encodedHeader = base64UrlEncode(header)
+  const encodedPayload = base64UrlEncode(payload)
+  return `${encodedHeader}.${encodedPayload}`
+}
 
 describe('AuthHelper', function () {
   describe('constructor checks', function () {
@@ -381,4 +406,153 @@ describe('AuthHelper', function () {
       ).to.throw(InvalidParameter)
     })
   })
+
+  context('JTW Auth', function () {
+    describe('_isJwtValid', function () {
+      test(AuthHelper._isJwtValid, () => {
+        given(dayjs().add(1, 'month').unix()).expect(true)
+        given(dayjs().add(2, 'minutes').unix()).expect(true)
+        given(dayjs().add(30, 'seconds').unix()).expect(false)
+        given(dayjs().unix()).expect(false)
+        given(dayjs().subtract(1, 'seconds').unix()).expect(false)
+      })
+    })
+
+    describe('_getJwtExpiry', function () {
+      it('extracts expiry from valid JWT', function () {
+        const nowPlus30Mins = dayjs().add(30, 'minutes').unix()
+        expect(
+          AuthHelper._getJwtExpiry(getMockJwt({ exp: nowPlus30Mins })),
+        ).to.equal(nowPlus30Mins)
+      })
+
+      it('caps expiry at max', function () {
+        const nowPlus1Hour = dayjs().add(1, 'hours').unix()
+        const nowPlus2Hours = dayjs().add(2, 'hours').unix()
+        expect(
+          AuthHelper._getJwtExpiry(getMockJwt({ exp: nowPlus2Hours })),
+        ).to.equal(nowPlus1Hour)
+      })
+
+      it('throws if JWT does not contain exp', function () {
+        expect(() => {
+          AuthHelper._getJwtExpiry(getMockJwt({}))
+        }).to.throw(InvalidResponse)
+      })
+
+      it('throws if JWT is invalid', function () {
+        expect(() => {
+          AuthHelper._getJwtExpiry('abc')
+        }).to.throw(InvalidResponse)
+      })
+    })
+
+    describe('withJwtAuth', function () {
+      const authHelper = new AuthHelper(
+        {
+          userKey: 'jwt_user',
+          passKey: 'jwt_pass',
+          authorizedOrigins: ['https://example.com'],
+          isRequired: false,
+        },
+        { private: { jwt_user: 'fred', jwt_pass: 'abc123' } },
+      )
+
+      beforeEach(function () {
+        clearJwtCache()
+      })
+
+      it('should use cached response if valid', async function () {
+        // the expiry is far enough in the future that the token
+        // will still be valid on the second hit
+        const mockToken = getMockJwt({ exp: dayjs().add(1, 'hours').unix() })
+
+        // .times(1) ensures if we try to make a second call to this endpoint,
+        // we will throw `Nock: No match for request`
+        nock('https://example.com')
+          .post('/login')
+          .times(1)
+          .reply(200, { token: mockToken })
+        const params1 = await authHelper.withJwtAuth(
+          { url: 'https://example.com/some-endpoint' },
+          'https://example.com/login',
+        )
+        expect(nock.isDone()).to.equal(true)
+        expect(params1).to.deep.equal({
+          options: {
+            headers: {
+              Authorization: `Bearer ${mockToken}`,
+            },
+          },
+          url: 'https://example.com/some-endpoint',
+        })
+
+        // second time round, we'll get the same response again
+        // but this time served from cache
+        const params2 = await authHelper.withJwtAuth(
+          { url: 'https://example.com/some-endpoint' },
+          'https://example.com/login',
+        )
+        expect(params2).to.deep.equal({
+          options: {
+            headers: {
+              Authorization: `Bearer ${mockToken}`,
+            },
+          },
+          url: 'https://example.com/some-endpoint',
+        })
+
+        nock.cleanAll()
+      })
+
+      it('should not use cached response if expired', async function () {
+        // this time we define a token expiry is close enough
+        // that the token will not be valid on the second call
+        const mockToken1 = getMockJwt({
+          exp: dayjs().add(20, 'seconds').unix(),
+        })
+        nock('https://example.com')
+          .post('/login')
+          .times(1)
+          .reply(200, { token: mockToken1 })
+        const params1 = await authHelper.withJwtAuth(
+          { url: 'https://example.com/some-endpoint' },
+          'https://example.com/login',
+        )
+        expect(nock.isDone()).to.equal(true)
+        expect(params1).to.deep.equal({
+          options: {
+            headers: {
+              Authorization: `Bearer ${mockToken1}`,
+            },
+          },
+          url: 'https://example.com/some-endpoint',
+        })
+
+        // second time round we make another network request
+        const mockToken2 = getMockJwt({
+          exp: dayjs().add(20, 'seconds').unix(),
+        })
+        nock('https://example.com')
+          .post('/login')
+          .times(1)
+          .reply(200, { token: mockToken2 })
+        const params2 = await authHelper.withJwtAuth(
+          { url: 'https://example.com/some-endpoint' },
+          'https://example.com/login',
+        )
+        expect(nock.isDone()).to.equal(true)
+        expect(params2).to.deep.equal({
+          options: {
+            headers: {
+              Authorization: `Bearer ${mockToken2}`,
+            },
+          },
+          url: 'https://example.com/some-endpoint',
+        })
+
+        nock.cleanAll()
+      })
+    })
+  })
 })

core/base-service/base-graphql.js

@@ -20,7 +20,7 @@ class BaseGraphqlService extends BaseService {
   /**
    * Parse data from JSON endpoint
    *
-   * @param {string} buffer JSON repsonse from upstream API
+   * @param {string} buffer JSON response from upstream API
    * @returns {object} Parsed response
    */
   _parseJson(buffer) {
@@ -50,8 +50,10 @@ class BaseGraphqlService extends BaseService {
    *    See {@link https://github.com/sindresorhus/got/blob/main/documentation/7-retry.md#errorcodes got error codes}
    *    for allowed keys
    *    and {@link module:core/base-service/errors~RuntimeErrorProps} for allowed values
+   * @param {number[]} [attrs.logErrors=[429]] An array of http error codes
+   *    that will be logged (to sentry, if configured).
    * @param {Function} [attrs.transformJson=data => data] Function which takes the raw json and transforms it before
-   * further procesing. In case of multiple query in a single graphql call and few of them
+   * further processing. In case of multiple query in a single graphql call and few of them
    * throw error, partial data might be used ignoring the error.
    * @param {Function} [attrs.transformErrors=defaultTransformErrors]
    *    Function which takes an errors object from a GraphQL
@@ -69,6 +71,7 @@ class BaseGraphqlService extends BaseService {
     options = {},
     httpErrorMessages = {},
     systemErrors = {},
+    logErrors = [429],
     transformJson = data => data,
     transformErrors = defaultTransformErrors,
   }) {
@@ -83,6 +86,7 @@ class BaseGraphqlService extends BaseService {
       options: mergedOptions,
       httpErrors: httpErrorMessages,
       systemErrors,
+      logErrors,
     })
     const json = transformJson(this._parseJson(buffer))
     if (json.errors) {

core/base-service/base-json.js

@@ -14,7 +14,7 @@ class BaseJsonService extends BaseService {
   /**
    * Parse data from JSON endpoint
    *
-   * @param {string} buffer JSON repsonse from upstream API
+   * @param {string} buffer JSON response from upstream API
    * @returns {object} Parsed response
    */
   _parseJson(buffer) {
@@ -40,6 +40,8 @@ class BaseJsonService extends BaseService {
    *    See {@link https://github.com/sindresorhus/got/blob/main/documentation/7-retry.md#errorcodes got error codes}
    *    for allowed keys
    *    and {@link module:core/base-service/errors~RuntimeErrorProps} for allowed values
+   * @param {number[]} [attrs.logErrors=[429]] An array of http error codes
+   *    that will be logged (to sentry, if configured).
    * @returns {object} Parsed response
    * @see https://github.com/sindresorhus/got/blob/main/documentation/2-options.md
    */
@@ -49,6 +51,7 @@ class BaseJsonService extends BaseService {
     options = {},
     httpErrors = {},
     systemErrors = {},
+    logErrors = [429],
   }) {
     const mergedOptions = {
       ...{ headers: { Accept: 'application/json' } },
@@ -59,6 +62,7 @@ class BaseJsonService extends BaseService {
       options: mergedOptions,
       httpErrors,
       systemErrors,
+      logErrors,
     })
     const json = this._parseJson(buffer)
     return this.constructor._validate(json, schema)

core/base-service/base-svg-scraping.js

@@ -63,6 +63,8 @@ class BaseSvgScrapingService extends BaseService {
    *    See {@link https://github.com/sindresorhus/got/blob/main/documentation/7-retry.md#errorcodes got error codes}
    *    for allowed keys
    *    and {@link module:core/base-service/errors~RuntimeErrorProps} for allowed values
+   * @param {number[]} [attrs.logErrors=[429]] An array of http error codes
+   *    that will be logged (to sentry, if configured).
    * @returns {object} Parsed response
    * @see https://github.com/sindresorhus/got/blob/main/documentation/2-options.md
    */
@@ -73,6 +75,7 @@ class BaseSvgScrapingService extends BaseService {
     options = {},
     httpErrors = {},
     systemErrors = {},
+    logErrors = [429],
   }) {
     const logTrace = (...args) => trace.logTrace('fetch', ...args)
     const mergedOptions = {
@@ -84,6 +87,7 @@ class BaseSvgScrapingService extends BaseService {
       options: mergedOptions,
       httpErrors,
       systemErrors,
+      logErrors,
     })
     logTrace(emojic.dart, 'Response SVG', buffer)
     const data = {

core/base-service/base-toml.js

@@ -0,0 +1,86 @@
+/**
+ * @module
+ */
+
+import emojic from 'emojic'
+import { parse } from 'smol-toml'
+import BaseService from './base.js'
+import { InvalidResponse } from './errors.js'
+import trace from './trace.js'
+
+/**
+ * Services which query a TOML endpoint should extend BaseTomlService
+ *
+ * @abstract
+ */
+class BaseTomlService extends BaseService {
+  /**
+   * Request data from an upstream API serving TOML,
+   * parse it and validate against a schema
+   *
+   * @param {object} attrs Refer to individual attrs
+   * @param {Joi} attrs.schema Joi schema to validate the response against
+   * @param {string} attrs.url URL to request
+   * @param {object} [attrs.options={}] Options to pass to got. See
+   *    [documentation](https://github.com/sindresorhus/got/blob/main/documentation/2-options.md)
+   * @param {object} [attrs.httpErrors={}] Key-value map of status codes
+   *    and custom error messages e.g: `{ 404: 'package not found' }`.
+   *    This can be used to extend or override the
+   *    [default](https://github.com/badges/shields/blob/master/core/base-service/check-error-response.js#L5)
+   * @param {object} [attrs.systemErrors={}] Key-value map of got network exception codes
+   *    and an object of params to pass when we construct an Inaccessible exception object
+   *    e.g: `{ ECONNRESET: { prettyMessage: 'connection reset' } }`.
+   *    See {@link https://github.com/sindresorhus/got/blob/main/documentation/7-retry.md#errorcodes got error codes}
+   *    for allowed keys
+   *    and {@link module:core/base-service/errors~RuntimeErrorProps} for allowed values
+   * @param {number[]} [attrs.logErrors=[429]] An array of http error codes
+   *    that will be logged (to sentry, if configured).
+   * @returns {object} Parsed response
+   * @see https://github.com/sindresorhus/got/blob/main/documentation/2-options.md
+   */
+  async _requestToml({
+    schema,
+    url,
+    options = {},
+    httpErrors = {},
+    systemErrors = {},
+    logErrors = [429],
+  }) {
+    const logTrace = (...args) => trace.logTrace('fetch', ...args)
+    const mergedOptions = {
+      ...{
+        headers: {
+          Accept:
+            // the official header should be application/toml - see https://toml.io/en/v1.0.0#mime-type
+            // but as this is not registered here https://www.iana.org/assignments/media-types/media-types.xhtml
+            // some apps use other mime-type like application/x-toml, text/plain etc....
+            'text/x-toml, text/toml, application/x-toml, application/toml, text/plain',
+        },
+      },
+      ...options,
+    }
+    const { buffer } = await this._request({
+      url,
+      options: mergedOptions,
+      httpErrors,
+      systemErrors,
+      logErrors,
+    })
+    let parsed
+    try {
+      parsed = parse(buffer.toString())
+    } catch (err) {
+      logTrace(emojic.dart, 'Response TOML (unparseable)', buffer)
+      throw new InvalidResponse({
+        prettyMessage: 'unparseable toml response',
+        underlyingError: err,
+      })
+    }
+    logTrace(emojic.dart, 'Response TOML (before validation)', parsed, {
+      deep: true,
+    })
+    return this.constructor._validate(parsed, schema)
+  }
+}
+
+export default BaseTomlService

core/base-service/base-toml.spec.js

@@ -0,0 +1,150 @@
+import Joi from 'joi'
+import { expect } from 'chai'
+import sinon from 'sinon'
+import BaseTomlService from './base-toml.js'
+
+const dummySchema = Joi.object({
+  requiredString: Joi.string().required(),
+}).required()
+
+class DummyTomlService extends BaseTomlService {
+  static category = 'cat'
+  static route = { base: 'foo' }
+
+  async handle() {
+    const { requiredString } = await this._requestToml({
+      schema: dummySchema,
+      url: 'http://example.com/foo.toml',
+    })
+    return { message: requiredString }
+  }
+}
+
+const expectedToml = `
+# example toml
+requiredString = "some-string"
+`
+
+const invalidSchemaToml = `
+# example toml - legal toml syntax but invalid schema
+unexpectedKey = "some-string"
+`
+
+const invalidTomlSyntax = `
+# example illegal toml syntax that can't be parsed
+missing= "space"
+colonsCantBeUsed: 42
+missing "assignment"
+`
+
+describe('BaseTomlService', function () {
+  describe('Making requests', function () {
+    let requestFetcher
+    beforeEach(function () {
+      requestFetcher = sinon.stub().returns(
+        Promise.resolve({
+          buffer: expectedToml,
+          res: { statusCode: 200 },
+        }),
+      )
+    })
+
+    it('invokes _requestFetcher', async function () {
+      await DummyTomlService.invoke(
+        { requestFetcher },
+        { handleInternalErrors: false },
+      )
+
+      expect(requestFetcher).to.have.been.calledOnceWith(
+        'http://example.com/foo.toml',
+        {
+          headers: {
+            Accept:
+              'text/x-toml, text/toml, application/x-toml, application/toml, text/plain',
+          },
+        },
+      )
+    })
+
+    it('forwards options to _requestFetcher', async function () {
+      class WithOptions extends DummyTomlService {
+        async handle() {
+          const { requiredString } = await this._requestToml({
+            schema: dummySchema,
+            url: 'http://example.com/foo.toml',
+            options: { method: 'POST', searchParams: { queryParam: 123 } },
+          })
+          return { message: requiredString }
+        }
+      }
+
+      await WithOptions.invoke(
+        { requestFetcher },
+        { handleInternalErrors: false },
+      )
+
+      expect(requestFetcher).to.have.been.calledOnceWith(
+        'http://example.com/foo.toml',
+        {
+          headers: {
+            Accept:
+              'text/x-toml, text/toml, application/x-toml, application/toml, text/plain',
+          },
+          method: 'POST',
+          searchParams: { queryParam: 123 },
+        },
+      )
+    })
+  })
+
+  describe('Making badges', function () {
+    it('handles valid toml responses', async function () {
+      const requestFetcher = async () => ({
+        buffer: expectedToml,
+        res: { statusCode: 200 },
+      })
+      expect(
+        await DummyTomlService.invoke(
+          { requestFetcher },
+          { handleInternalErrors: false },
+        ),
+      ).to.deep.equal({
+        message: 'some-string',
+      })
+    })
+
+    it('handles toml responses which do not match the schema', async function () {
+      const requestFetcher = async () => ({
+        buffer: invalidSchemaToml,
+        res: { statusCode: 200 },
+      })
+      expect(
+        await DummyTomlService.invoke(
+          { requestFetcher },
+          { handleInternalErrors: false },
+        ),
+      ).to.deep.equal({
+        isError: true,
+        color: 'lightgray',
+        message: 'invalid response data',
+      })
+    })
+
+    it('handles unparseable toml responses', async function () {
+      const requestFetcher = async () => ({
+        buffer: invalidTomlSyntax,
+        res: { statusCode: 200 },
+      })
+      expect(
+        await DummyTomlService.invoke(
+          { requestFetcher },
+          { handleInternalErrors: false },
+        ),
+      ).to.deep.equal({
+        isError: true,
+        color: 'lightgray',
+        message: 'unparseable toml response',
+      })
+    })
+  })
+})

core/base-service/base-xml.js

@@ -34,6 +34,8 @@ class BaseXmlService extends BaseService {
    *    See {@link https://github.com/sindresorhus/got/blob/main/documentation/7-retry.md#errorcodes got error codes}
    *    for allowed keys
    *    and {@link module:core/base-service/errors~RuntimeErrorProps} for allowed values
+   * @param {number[]} [attrs.logErrors=[429]] An array of http error codes
+   *    that will be logged (to sentry, if configured).
    * @param {object} [attrs.parserOptions={}] Options to pass to fast-xml-parser. See
    *    [documentation](https://github.com/NaturalIntelligence/fast-xml-parser#xml-to-json)
    * @returns {object} Parsed response
@@ -46,6 +48,7 @@ class BaseXmlService extends BaseService {
     options = {},
     httpErrors = {},
     systemErrors = {},
+    logErrors = [429],
     parserOptions = {},
   }) {
     const logTrace = (...args) => trace.logTrace('fetch', ...args)
@@ -58,6 +61,7 @@ class BaseXmlService extends BaseService {
       options: mergedOptions,
       httpErrors,
       systemErrors,
+      logErrors,
     })
     const validateResult = XMLValidator.validate(buffer)
     if (validateResult !== true) {

core/base-service/base-yaml.js

@@ -33,6 +33,8 @@ class BaseYamlService extends BaseService {
    *    See {@link https://github.com/sindresorhus/got/blob/main/documentation/7-retry.md#errorcodes got error codes}
    *    for allowed keys
    *    and {@link module:core/base-service/errors~RuntimeErrorProps} for allowed values
+   * @param {number[]} [attrs.logErrors=[429]] An array of http error codes
+   *    that will be logged (to sentry, if configured).
    * @param {object} [attrs.encoding='utf8'] Character encoding
    * @returns {object} Parsed response
    * @see https://github.com/sindresorhus/got/blob/main/documentation/2-options.md
@@ -43,6 +45,7 @@ class BaseYamlService extends BaseService {
     options = {},
     httpErrors = {},
     systemErrors = {},
+    logErrors = [429],
     encoding = 'utf8',
   }) {
     const logTrace = (...args) => trace.logTrace('fetch', ...args)
@@ -60,6 +63,7 @@ class BaseYamlService extends BaseService {
       options: mergedOptions,
       httpErrors,
       systemErrors,
+      logErrors,
     })
     let parsed
     try {

core/base-service/base.js

@@ -21,6 +21,7 @@ import {
 } from './errors.js'
 import { validateExample, transformExample } from './examples.js'
 import { fetch } from './got.js'
+import { getEnum } from './openapi.js'
 import {
   makeFullUrl,
   assertValidRoute,
@@ -102,6 +103,26 @@ class BaseService {
     throw new Error(`Route not defined for ${this.name}`)
   }
 
+  /**
+   * Extract an array of allowed values from this service's route pattern
+   * for a given route parameter
+   *
+   * @param {string} param The name of a param in this service's route pattern
+   * @returns {string[]} Array of allowed values for this param
+   */
+  static getEnum(param) {
+    if (!('pattern' in this.route)) {
+      throw new Error('getEnum() requires route to have a .pattern property')
+    }
+    const enumeration = getEnum(this.route.pattern, param)
+    if (!Array.isArray(enumeration)) {
+      throw new Error(
+        `Could not extract enum for param ${param} from pattern ${this.route.pattern}`,
+      )
+    }
+    return enumeration
+  }
+
   /**
    * Configuration for the authentication helper that prepares credentials
    * for upstream requests.
@@ -242,7 +263,13 @@ class BaseService {
     this._metricHelper = metricHelper
   }
 
-  async _request({ url, options = {}, httpErrors = {}, systemErrors = {} }) {
+  async _request({
+    url,
+    options = {},
+    httpErrors = {},
+    systemErrors = {},
+    logErrors = [429],
+  }) {
     const logTrace = (...args) => trace.logTrace('fetch', ...args)
     let logUrl = url
     const logOptions = Object.assign({}, options)
@@ -269,7 +296,7 @@ class BaseService {
     )
     await this._meterResponse(res, buffer)
     logTrace(emojic.dart, 'Response status code', res.statusCode)
-    return checkErrorResponse(httpErrors)({ buffer, res })
+    return checkErrorResponse(httpErrors, logErrors)({ buffer, res })
   }
 
   static enabledMetrics = []

core/base-service/base.spec.js

@@ -322,7 +322,7 @@ describe('BaseService', function () {
   })
 
   describe('ScoutCamp integration', function () {
-    // TODO Strangly, without the useless escape the regexes do not match in Node 12.
+    // TODO Strangely, without the useless escape the regexes do not match in Node 12.
     // eslint-disable-next-line no-useless-escape
     const expectedRouteRegex = /^\/foo(?:\/([^\/#\?]+?))(|\.svg|\.json)$/
 
@@ -539,6 +539,7 @@ describe('BaseService', function () {
       ).to.not.contain('service_response_bytes_bucket')
     })
   })
+
   describe('auth', function () {
     class AuthService extends DummyService {
       static auth = {
@@ -592,4 +593,44 @@ describe('BaseService', function () {
       })
     })
   })
+
+  describe('getEnum', function () {
+    class EnumService extends DummyService {
+      static route = {
+        base: 'foo',
+        pattern: ':namedParamA/:namedParamB(this|that)',
+        queryParamSchema,
+      }
+    }
+
+    it('returns an array of allowed values', async function () {
+      expect(EnumService.getEnum('namedParamB')).to.deep.equal(['this', 'that'])
+    })
+
+    it('throws if param name is invalid', async function () {
+      expect(() => EnumService.getEnum('notAValidParam')).to.throw(
+        'Could not extract enum for param notAValidParam from pattern :namedParamA/:namedParamB(this|that)',
+      )
+    })
+
+    it('throws if param name is not an enum', async function () {
+      expect(() => EnumService.getEnum('namedParamA')).to.throw(
+        'Could not extract enum for param namedParamA from pattern :namedParamA/:namedParamB(this|that)',
+      )
+    })
+
+    it('throws if route does not have a pattern', async function () {
+      class FormatService extends DummyService {
+        static route = {
+          base: 'foo',
+          format: '([^/]+?)',
+          queryParamSchema,
+        }
+      }
+
+      expect(() => FormatService.getEnum('notAValidParam')).to.throw(
+        'getEnum() requires route to have a .pattern property',
+      )
+    })
+  })
 })

core/base-service/check-error-response.js

@@ -1,3 +1,4 @@
+import log from '../server/log.js'
 import { NotFound, InvalidResponse, Inaccessible } from './errors.js'
 
 const defaultErrorMessages = {
@@ -5,7 +6,7 @@ const defaultErrorMessages = {
   429: 'rate limited by upstream service',
 }
 
-export default function checkErrorResponse(httpErrors = {}) {
+export default function checkErrorResponse(httpErrors = {}, logErrors = [429]) {
   return async function ({ buffer, res }) {
     let error
     httpErrors = { ...defaultErrorMessages, ...httpErrors }
@@ -25,6 +26,11 @@ export default function checkErrorResponse(httpErrors = {}) {
         error = new InvalidResponse(props)
       }
     }
+
+    if (logErrors.includes(res.statusCode)) {
+      log.error(new Error(`${res.statusCode} calling ${res.requestUrl.origin}`))
+    }
+
     if (error) {
       error.response = res
       error.buffer = buffer

core/base-service/check-error-response.spec.js

@@ -47,7 +47,7 @@ describe('async error handler', function () {
 
   context('when status is 429', function () {
     const buffer = Buffer.from('some stuff')
-    const res = { statusCode: 429 }
+    const res = { statusCode: 429, requestUrl: new URL('https://example.com/') }
 
     it('throws InvalidResponse', async function () {
       try {

core/base-service/index.js

@@ -3,6 +3,7 @@ import BaseJsonService from './base-json.js'
 import BaseGraphqlService from './base-graphql.js'
 import BaseStaticService from './base-static.js'
 import BaseSvgScrapingService from './base-svg-scraping.js'
+import BaseTomlService from './base-toml.js'
 import BaseXmlService from './base-xml.js'
 import BaseYamlService from './base-yaml.js'
 import deprecatedService from './deprecated-service.js'
@@ -23,6 +24,7 @@ export {
   BaseGraphqlService,
   BaseStaticService,
   BaseSvgScrapingService,
+  BaseTomlService,
   BaseXmlService,
   BaseYamlService,
   deprecatedService,

core/base-service/openapi.js

@@ -31,7 +31,7 @@ function getCodeSamples(altText) {
     {
       lang: 'reStructuredText',
       label: 'rSt',
-      source: `.. image:: $url\n:   alt: ${altText}`,
+      source: `.. image:: $url\n   :alt: ${altText}`,
     },
     {
       lang: 'AsciiDoc',
@@ -241,10 +241,10 @@ function category2openapi(category, services) {
           name: 'style',
           in: 'query',
           required: false,
-          description:
-            'One of: flat (default), flat-square, plastic, for-the-badge, social',
+          description: 'If not specified, the defautl style is "flat".',
           schema: {
             type: 'string',
+            enum: ['flat', 'flat-square', 'plastic', 'for-the-badge', 'social'],
           },
           example: 'flat',
         },
@@ -363,7 +363,7 @@ function pathParam({
  *   { name: 'name2', example: 'example2' },
  * )
  * ```
- * is equivilent to
+ * is equivalent to
  * ```
  * const params = [
  *   pathParam({ name: 'name1', example: 'example1' }),
@@ -409,11 +409,11 @@ function queryParam({
  *   { name: 'name2', example: 'example2' },
  * )
  * ```
- * is equivilent to
+ * is equivalent to
  * ```
  * const params = [
  *   queryParam({ name: 'name1', example: 'example1' }),
- *   queryParams({ name: 'name2', example: 'example2' }),
+ *   queryParam({ name: 'name2', example: 'example2' }),
  * ]
  * ```
  *
@@ -466,4 +466,11 @@ function queryParams(...params) {
  * @property {boolean} allowEmptyValue If true, allows the ability to pass an empty value to this parameter
  */
 
-export { category2openapi, pathParam, pathParams, queryParam, queryParams }
+export {
+  category2openapi,
+  getEnum,
+  pathParam,
+  pathParams,
+  queryParam,
+  queryParams,
+}

core/base-service/openapi.spec.js

@@ -88,9 +88,11 @@ const expected = {
         name: 'style',
         in: 'query',
         required: false,
-        description:
-          'One of: flat (default), flat-square, plastic, for-the-badge, social',
-        schema: { type: 'string' },
+        description: 'If not specified, the defautl style is "flat".',
+        schema: {
+          enum: ['flat', 'flat-square', 'plastic', 'for-the-badge', 'social'],
+          type: 'string',
+        },
         example: 'flat',
       },
       logo: {
@@ -192,7 +194,7 @@ const expected = {
           {
             lang: 'reStructuredText',
             label: 'rSt',
-            source: '.. image:: $url\n:   alt: OpenApiService Summary',
+            source: '.. image:: $url\n   :alt: OpenApiService Summary',
           },
           {
             lang: 'AsciiDoc',
@@ -248,7 +250,7 @@ const expected = {
             lang: 'reStructuredText',
             label: 'rSt',
             source:
-              '.. image:: $url\n:   alt: OpenApiService Summary (with Tag)',
+              '.. image:: $url\n   :alt: OpenApiService Summary (with Tag)',
           },
           {
             lang: 'AsciiDoc',
@@ -301,7 +303,7 @@ const expected = {
           {
             lang: 'reStructuredText',
             label: 'rSt',
-            source: '.. image:: $url\n:   alt: LegacyService Title (with Tag)',
+            source: '.. image:: $url\n   :alt: LegacyService Title (with Tag)',
           },
           {
             lang: 'AsciiDoc',
@@ -347,7 +349,7 @@ const expected = {
           {
             lang: 'reStructuredText',
             label: 'rSt',
-            source: '.. image:: $url\n:   alt: LegacyService Title (with Tag)',
+            source: '.. image:: $url\n   :alt: LegacyService Title (with Tag)',
           },
           {
             lang: 'AsciiDoc',

core/server/server.js

@@ -128,6 +128,7 @@ const publicConfigSchema = Joi.object({
       },
       restApiVersion: Joi.date().raw().required(),
     },
+    gitea: defaultService,
     gitlab: defaultService,
     jira: defaultService,
     jenkins: Joi.object({
@@ -162,11 +163,15 @@ const publicConfigSchema = Joi.object({
 
 const privateConfigSchema = Joi.object({
   azure_devops_token: Joi.string(),
+  curseforge_api_key: Joi.string(),
   discord_bot_token: Joi.string(),
+  dockerhub_username: Joi.string(),
+  dockerhub_pat: Joi.string(),
   drone_token: Joi.string(),
   gh_client_id: Joi.string(),
   gh_client_secret: Joi.string(),
   gh_token: Joi.string(),
+  gitea_token: Joi.string(),
   gitlab_token: Joi.string(),
   jenkins_user: Joi.string(),
   jenkins_pass: Joi.string(),
@@ -183,6 +188,8 @@ const privateConfigSchema = Joi.object({
   obs_user: Joi.string(),
   obs_pass: Joi.string(),
   redis_url: Joi.string().uri({ scheme: ['redis', 'rediss'] }),
+  opencollective_token: Joi.string(),
+  pepy_key: Joi.string(),
   postgres_url: Joi.string().uri({ scheme: 'postgresql' }),
   sentry_dsn: Joi.string(),
   sl_insight_userUuid: Joi.string(),

doc/TUTORIAL.md

@@ -25,7 +25,7 @@ and learn about the [GitHub workflow](http://try.github.io/).
 
 #### Node, NPM
 
-Node >=16 and NPM 9.x is required. If you don't already have them,
+Node >=20 and NPM 9.x or 10.x is required. If you don't already have them,
 install node and npm: https://nodejs.org/en/download/
 
 ### Setup a dev install
@@ -96,6 +96,8 @@ Other classes implement useful behavior on top of [BaseService].
   implements methods for performing requests to an XML API and schema validation.
 - [BaseYamlService](https://contributing.shields.io/module-core_base-service_base-yaml-BaseYamlService.html)
   implements methods for performing requests to a YAML API and schema validation.
+- [BaseTomlService](https://contributing.shields.io/module-core_base-service_base-toml-BaseTomlService.html)
+  implements methods for performing requests to a TOML API and schema validation.
 - [BaseSvgScrapingService](https://contributing.shields.io/module-core_base-service_base-svg-scraping-BaseSvgScrapingService.html)
   implements methods for retrieving information from existing third-party badges.
 - [BaseGraphqlService](https://contributing.shields.io/module-core_base-service_base-graphql-BaseGraphqlService.html)
@@ -132,17 +134,17 @@ export default class Example extends BaseService {
 
 Description of the code:
 
-1. Our service badge class will extend `BaseService` so we need to require it. Variables are declared with `const` and `let` in preference to `var`.
+1. Our service badge class will extend `BaseService` so we need to import it.
 2. Our module must export a class which extends `BaseService`.
-3. Returns the name of the category to sort this badge into (eg. "build"). Used to sort the examples on the main [shields.io](https://shields.io) website. [Here](https://github.com/badges/shields/blob/master/services/categories.js) is the list of the valid categories. See [section 4.4](#44-adding-an-example-to-the-front-page) for more details on examples.
-4. `route()` declares the URL path at which the service operates. It also maps components of the URL path to handler parameters.
+3. Returns the name of the category to sort this badge into (eg. "build"). Used to sort the examples on the main [shields.io](https://shields.io) website. [Here](https://github.com/badges/shields/blob/master/services/categories.js) is the list of the valid categories. See [section 4.4](#44-adding-documentation-to-the-frontend) for more details.
+4. `route` declares the URL path at which the service operates. It also maps components of the URL path to handler parameters.
    - `base` defines the first part of the URL that doesn't change, e.g. `/example/`.
    - `pattern` defines the variable part of the route, everything that comes after `/example/`. It can include any
      number of named parameters. These are converted into
      regular expressions by [`path-to-regexp`][path-to-regexp].
      Because a service instance won't be created until it's time to handle a request, the route and other metadata must be obtained by examining the classes themselves. [That's why they're marked `static`.][static]
    - There is additional documentation on conventions for [designing badge URLs](./badge-urls.md)
-5. All badges must implement the `async handle()` function that receives parameters to render the badge. Parameters of `handle()` will match the name defined in `route()` Because we're capturing a single variable called `text` our function signature is `async handle({ text })`. `async` is needed to let JavaScript do other things while we are waiting for result from external API. Although in this simple case, we don't make any external calls. Our `handle()` function should return an object with 3 properties:
+5. All badges must implement the `async handle()` function that receives parameters to render the badge. Parameters of `handle()` will match the name defined in `route` Because we're capturing a single variable called `text` our function signature is `async handle({ text })`. `async` is needed to let JavaScript do other things while we are waiting for result from external API. Although in this simple case, we don't make any external calls. Our `handle()` function should return an object with 3 properties:
    - `label`: the text on the left side of the badge
    - `message`: the text on the right side of the badge - here we are passing through the parameter we captured in the route regex
    - `color`: the background color of the right side of the badge
@@ -221,11 +223,11 @@ Description of the code:
 2. Our badge will query a JSON API so we will extend `BaseJsonService` instead of `BaseService`. This contains some helpers to reduce the need for boilerplate when calling a JSON API.
 3. We perform input validation by defining a schema which we expect the JSON we receive to conform to. This is done using [Joi](https://github.com/hapijs/joi). Defining a schema means we can ensure the JSON we receive meets our expectations and throw an error if we receive unexpected input without having to explicitly code validation checks. The schema also acts as a filter on the JSON object. Any properties we're going to reference need to be validated, otherwise they will be filtered out. In this case our schema declares that we expect to receive an object which must have a property called 'version', which is a string. There is further documentation on [input validation](input-validation.md).
 4. Our module exports a class which extends `BaseJsonService`
-5. Returns the name of the category to sort this badge into (eg. "build"). Used to sort the examples on the main [shields.io](https://shields.io) website. [Here](https://github.com/badges/shields/blob/master/services/categories.js) is the list of the valid categories. See [section 4.4](#44-adding-an-example-to-the-front-page) for more details on examples.
+5. Returns the name of the category to sort this badge into (eg. "build"). Used to sort the examples on the main [shields.io](https://shields.io) website. [Here](https://github.com/badges/shields/blob/master/services/categories.js) is the list of the valid categories. See [section 4.4](#44-adding-documentation-to-the-frontend) for more details.
 6. As with our previous badge, we need to declare a route. This time we will capture a variable called `gem`.
-7. We can use `defaultBadgeData()` to set a default `color`, `logo` and/or `label`. If `handle()` doesn't return any of these keys, we'll use the default. Instead of explicitly setting the label text when we return a badge object, we'll use `defaultBadgeData()` here to define it declaratively.
+7. We can use `defaultBadgeData` to set a default `color`, `logo` and/or `label`. If `handle()` doesn't return any of these keys, we'll use the default. Instead of explicitly setting the label text when we return a badge object, we'll use `defaultBadgeData` here to define it declaratively.
 8. We now jump to the bottom of the example code to the function all badges must implement: `async handle()`. This is the function the server will invoke to handle an incoming request. Because our URL pattern captures a variable called `gem`, our function signature is `async handle({ gem })`. We usually separate the process of generating a badge into 2 stages or concerns: fetch and render. The `fetch()` function is responsible for calling an API endpoint to get data. The `render()` function formats the data for display. In a case where there is a lot of calculation or intermediate steps, this pattern may be thought of as fetch, transform, render and it might be necessary to define some helper functions to assist with the 'transform' step.
-9. Working our way upward, the `async fetch()` method is responsible for calling an API endpoint to get data. Extending `BaseJsonService` gives us the helper function `_requestJson()`. Note here that we pass the schema we defined in step 4 as an argument. `_requestJson()` will deal with validating the response against the schema and throwing an error if necessary.
+9. Working our way upward, the `async fetch()` method is responsible for calling an API endpoint to get data. Extending `BaseJsonService` gives us the helper function `_requestJson()`. Note here that we pass the schema we defined in step 3 as an argument. `_requestJson()` will deal with validating the response against the schema and throwing an error if necessary.
 
    - `_requestJson()` automatically adds an Accept header, checks the status code, parses the response as JSON, and returns the parsed response.
    - `_requestJson()` uses [got](https://github.com/sindresorhus/got) to perform the HTTP request. Options can be passed to got, including method, query string, and headers. If headers are provided they will override the ones automatically set by `_requestJson()`. There is no need to specify json, as the JSON parsing is handled by `_requestJson()`. See the `got` docs for [supported options](https://github.com/sindresorhus/got/blob/main/documentation/2-options.md).
@@ -243,7 +245,7 @@ Description of the code:
      })
      ```
 
-10. Upward still, the `static render()` method is responsible for formatting the data for display. `render()` is a pure function so we can make it a `static` method. By convention we declare functions which don't reference `this` as `static`. We could explicitly return an object here, as we did in the previous example. In this case, we will hand the version string off to `renderVersionBadge()` which will format it consistently and set an appropriate color. Because `renderVersionBadge()` doesn't return a `label` key, the default label we defined in `defaultBadgeData()` will be used when we generate the badge.
+10. Upward still, the `static render()` method is responsible for formatting the data for display. `render()` is a pure function so we can make it a `static` method. By convention we declare functions which don't reference `this` as `static`. We could explicitly return an object here, as we did in the previous example. In this case, we will hand the version string off to `renderVersionBadge()` which will format it consistently and set an appropriate color. Because `renderVersionBadge()` doesn't return a `label` key, the default label we defined in `defaultBadgeData` will be used when we generate the badge.
 
 This code allows us to call this URL <https://img.shields.io/gem/v/formatador> to generate this badge: ![](https://img.shields.io/gem/v/formatador)
 
@@ -267,42 +269,88 @@ import { NotFound } from '../index.js'
 throw new NotFound({ prettyMessage: 'package not found' })
 ```
 
-### (4.4) Adding an Example to the Front Page
+### (4.4) Adding Documentation to the Frontend
 
-Once we have implemented our badge, we can add it to the index so that users can discover it. We will do this by adding an additional method `examples()` to our class.
+To render the shields.io website, we produce an [OpenAPI 3 specification](https://swagger.io/specification/) which describes the available badge endpoints. Then we use that specification to render the frontend.
+
+Once we have implemented our badge, we want to add it to the index so that users can discover it. We will do this by adding an additional object `openApi` to our class. This object contains an [OpenAPI Paths Object](https://swagger.io/specification/#paths-object) describing the endpoint or endpoints exposed by this service class.
 
 ```js
+// (1)
+import { pathParams } from '../index.js'
+
 export default class GemVersion extends BaseJsonService {
   // ...
 
-  // (1)
+  // (2)
   static category = 'version'
 
-  // (2)
-  static examples = [
-    {
-      // (3)
-      title: 'Gem',
-      namedParams: { gem: 'formatador' },
-      staticPreview: this.render({ version: '2.1.0' }),
-      keywords: ['ruby'],
+  static openApi = {
+    // (3)
+    '/gem/v/{gem}': {
+      // (4)
+      get: {
+        // (5)
+        summary: 'Gem Version',
+        description:
+          '[Ruby Gems](https://rubygems.org/) is a registry for ruby libraries',
+        // (6)
+        parameters: pathParams({
+          name: 'gem',
+          description: 'Name of the Ruby Gem',
+          example: 'formatador',
+        }),
+      },
     },
-  ]
+  }
 }
 ```
 
-1. We defined category earlier in the tutorial. The `category()` property defines which heading in the index our example will appear under.
-2. The examples property defines an array of examples. In this case the array will contain a single object, but in some cases it is helpful to provide multiple usage examples.
-3. Our example object should contain the following properties:
-   - `title`: Descriptive text that will be shown next to the badge
-   - `namedParams`: Provide a valid example of params we can substitute into
-     the pattern. In this case we need a valid ruby gem, so we've picked [formatador](https://rubygems.org/gems/formatador).
-   - `staticPreview`: On the index page we want to show an example badge, but for performance reasons we want that example to be generated without making an API call. `staticPreview` should be populated by calling our `render()` method with some valid data.
-   - `keywords`: If we want to provide additional keywords other than the title and the category, we can add them here. This helps users to search for relevant badges.
+1. There are four helper functions we can use to assemble [Open API Parameter objects](https://swagger.io/specification/#parameter-object). These are:
+
+   - `pathParam` - returns a single Parameter object describing a single path parameter
+   - `pathParams` - returns an array of path parameter objects
+   - `queryParam` - returns a single Parameter object describing a single query parameter
+   - `queryParams` - returns an array of query parameter objects
+
+   These four helper functions are documented in more detail at http://contributing.shields.io/module-core_base-service_openapi.html
+
+2. We defined category earlier in the tutorial. The `category` property defines which heading in the index our example will appear under.
+3. The keys of the `openApi` object are routes. In this case we only need to describe one route. In some cases, a service class can define more than one badge route. Open API doesn't have the concept of optional path parameters (more specifically, `in: 'path'` implies `required: true`) so if there are any optional path parameters in our route, our `openApi` object needs to describe two URLs: one without the optional parameter, and another with it.
+4. The HTTP method. Shields only allows GET requests, so this is always `get`.
+5. `summary` (required) is a short title or description of the badge. `description` is an optional longer description or additional documentation. We can use markdown or HTML syntax inside the `description` field.
+6. `parameters` is an array of [Open API Parameter objects](https://swagger.io/specification/#parameter-object) describing any parameters we can pass to this route. This array should include all path parameters included in the key that this value object describes and all relevant query parameters. As a minimum, we need to supply `name` and `example`. The example must be a valid example of a value we can provide for this parameter. In this case we need a valid ruby gem, so we've picked [formatador](https://rubygems.org/gems/formatador). There are also optional keys we can pass. The code
+
+   ```js
+   parameters: pathParams({
+     name: 'gem',
+     description: 'Name of the Ruby Gem',
+     example: 'formatador',
+   })
+   ```
+
+   is equivalent to
+
+   ```js
+   parameters: [
+     {
+       name: 'gem',
+       in: 'path',
+       required: true,
+       schema: { type: 'string' },
+       example: 'formatador',
+       description: 'Name of the Ruby Gem',
+     },
+   ]
+   ```
+
+   but we have used the helper function `pathParams` to imply some defaults and reduce the amount of code we need to write by hand.
 
 Save, run `npm start`, and you can see it [locally](http://127.0.0.1:3000/).
 
-If you update `examples`, you don't have to restart the server. Run `npm run defs` in another terminal window and the frontend will update.
+If you update `openApi`, you don't have to restart the server. Run `npm run prestart` in another terminal window and the frontend will update.
+
+Note: Some services define this information in an array property called `examples`. This is deprecated and we're in the process of converting them. New services should declare an `openApi` object.
 
 ### (4.5) Write Tests<!-- Change the link below when you change the heading -->
 

doc/input-validation.md

@@ -24,6 +24,8 @@ When we receive input data from an upstream API, we perform input validation to:
 
 - We don't need to validate characteristics we don't rely on. For example, if we're just going to render a version on a badge with the same exact value from the API response and do not need to sort or transform the value, then it doesn't matter what format the version number is in. We can use a very relaxed schema to validate in this case, e.g. `Joi.string().required()`
 
+- http://mterczynski.pl/joi-schema-generator/ is a tool that can be used to reverse engineer a schema from an API response. This can be a great starting point to tweak from. If using this as a starting point, remember to remove fields we don't rely on to render a badge.
+
 - If theory (docs) and practice (real-world API responses) conflict, real-world outputs take precedence over documented behaviour. e.g: if the docs say version is a semver but we learn that there are real-world packages where the version number is `0.3b` or `1.2.1.27` then we should accept those values in preference to enforcing the documented API behaviour.
 
 - Shields is descriptive rather than prescriptive. We reflect the established norms of the communities we serve.

doc/self-hosting.md

@@ -4,13 +4,13 @@ This document describes how to host your own shields server either from source o
 
 ## Installing from Source
 
-You will need Node 16 or later, which you can install using a
+You will need Node 20 or later, which you can install using a
 [package manager][].
 
 On Ubuntu / Debian:
 
 ```sh
-curl -sL https://deb.nodesource.com/setup_16.x | sudo -E bash -; sudo apt-get install -y nodejs
+curl -sL https://deb.nodesource.com/setup_20.x | sudo -E bash -; sudo apt-get install -y nodejs
 ```
 
 ```sh

doc/server-secrets.md

@@ -97,15 +97,40 @@ self-hosted Shields installation access to private repositories hosted on bitbuc
 Bitbucket badges use basic auth. Provide a username and password to give your
 self-hosted Shields installation access to a private Bitbucket Server instance.
 
+### CurseForge
+
+- `CURSEFORGE_API_KEY` (yml: `private.curseforge_api_key`)
+
+A CurseForge API key is required to use the [CurseForge API][cf api]. To obtain
+an API key, [signup to CurseForge Console][cf signup] with a Google account and
+create an organization, then go to the [API keys page][cf api key] and copy the
+generated API key.
+
+[cf api]: https://docs.curseforge.com
+[cf signup]: https://console.curseforge.com/#/signup
+[cf api key]: https://console.curseforge.com/#/api-keys
+
 ### Discord
 
-Using a token for Dicsord is optional but will allow higher API rates.
+Using a token for Discord is optional but will allow higher API rates.
 
 - `DISCORD_BOT_TOKEN` (yml: `discord_bot_token`)
 
 Register an application in the [Discord developer console](https://discord.com/developers).
 To obtain a token, simply create a bot for your application.
 
+### DockerHub
+
+Using authentication for DockerHub is optional but can be used to allow
+higher API rates or access to private repos.
+
+- `DOCKERHUB_USER` (yml: `private.dockerhub_username`)
+- `DOCKERHUB_PAT` (yml: `private.dockerhub_pat`)
+
+`DOCKERHUB_PAT` is a Personal Access Token. Generate a token in your
+[account security settings](https://hub.docker.com/settings/security) with
+"Read-Only" or "Public Repo Read-Only", depending on your needs.
+
 ### Drone
 
 - `DRONE_ORIGINS` (yml: `public.services.drone.authorizedOrigins`)
@@ -154,6 +179,15 @@ These settings are used by shields.io for GitHub OAuth app authorization
 but will not be necessary for most self-hosted installations. See
 [production-hosting.md](./production-hosting.md).
 
+### Gitea
+
+- `GITEA_ORIGINS` (yml: `public.services.gitea.authorizedOrigins`)
+- `GITEA_TOKEN` (yml: `private.gitea_token`)
+
+A Gitea [Personal Access Token][gitea-pat] is required for accessing private content. If you need a Gitea token for your self-hosted Shields server then we recommend limiting the scopes to the minimal set necessary for the badges you are using.
+
+[gitea-pat]: https://docs.gitea.com/development/api-usage#generating-and-listing-api-tokens
+
 ### GitLab
 
 - `GITLAB_ORIGINS` (yml: `public.services.gitlab.authorizedOrigins`)
@@ -218,7 +252,7 @@ installation access to private npm packages
 
 [npm token]: https://docs.npmjs.com/getting-started/working_with_tokens
 
-## Open Build Service
+### Open Build Service
 
 - `OBS_USER` (yml: `private.obs_user`)
 - `OBS_PASS` (yml: `private.obs_user`)
@@ -233,6 +267,22 @@ they can only be scoped to execute specific actions on a POST request. This
 means however, that an actual account is required to read the build status
 of a package.
 
+### OpenCollective
+
+- `OPENCOLLECTIVE_TOKEN` (yml: `opencollective_token`)
+
+OpenCollective's GraphQL API only allows 10 reqs/minute for anonymous users.
+An [API token](https://graphql-docs-v2.opencollective.com/access)
+can be provided to access a higher rate limit of 100 reqs/minute.
+
+### Pepy
+
+- `PEPY_KEY` (yml: `pepy_key`)
+
+The Pepy API requires authentication. To obtain a key,
+Create an account, sign in and obtain generate a key on your
+[account page](https://www.pepy.tech/user).
+
 ### SymfonyInsight (formerly Sensiolabs)
 
 - `SL_INSIGHT_USER_UUID` (yml: `private.sl_insight_userUuid`)

frontend/blog/2023-11-29-simpleicons10.md

@@ -0,0 +1,14 @@
+---
+slug: simple-icons-10
+title: Simple Icons 10
+authors:
+  name: chris48s
+  title: Shields.io Core Team
+  url: https://github.com/chris48s
+  image_url: https://avatars.githubusercontent.com/u/6025893
+tags: []
+---
+
+Logos on Shields.io are provided by SimpleIcons. We've recently upgraded to SimpleIcons 10. This release removes 45 icons. A full list of the removals can be found in the [release notes](https://github.com/simple-icons/simple-icons/releases/tag/10.0.0).
+
+Please remember that we are just consumers of SimpleIcons. Decisions about changes and removals are made by the [SimpleIcons](https://github.com/simple-icons/simple-icons) project.

frontend/docusaurus.config.cjs

@@ -92,10 +92,6 @@ const config = {
                 label: 'Discord',
                 href: 'https://discord.gg/HjJCwm5',
               },
-              {
-                label: 'Twitter',
-                href: 'https://twitter.com/shields_io',
-              },
               {
                 label: 'Awesome Badges',
                 href: 'https://github.com/badges/awesome-badges',

frontend/src/pages/community.md

@@ -23,7 +23,7 @@ Shields.io is possible thanks to the people and companies who donate money, serv
 
 <p>
     <object
-        data="https://opencollective.com/shields/sponsors.svg?avatarHeight=80&width=600"
+        data="https://opencollective.com/shields/tiers/sponsor.svg?avatarHeight=80&width=600"
         class="opencollective-image"
     ></object>
 </p>
@@ -34,7 +34,7 @@ Shields.io is possible thanks to the people and companies who donate money, serv
 
 <p>
     <object
-        data="https://opencollective.com/shields/backers.svg?width=600"
+        data="https://opencollective.com/shields/tiers/backer.svg?width=600"
         class="opencollective-image">
     </object>
 </p>

package.json

@@ -21,30 +21,30 @@
     "url": "https://github.com/badges/shields"
   },
   "dependencies": {
-    "@renovate/pep440": "^1.0.0",
-    "@renovatebot/ruby-semver": "^2.1.11",
-    "@sentry/node": "^7.60.1",
+    "@renovatebot/pep440": "^3.0.17",
+    "@renovatebot/ruby-semver": "^3.0.22",
+    "@sentry/node": "^7.91.0",
     "@shields_io/camp": "^18.1.2",
     "@xmldom/xmldom": "0.8.10",
     "badge-maker": "file:badge-maker",
     "bytes": "^3.1.2",
-    "camelcase": "^7.0.1",
+    "camelcase": "^8.0.0",
     "chalk": "^5.3.0",
     "check-node-version": "^4.2.1",
     "cloudflare-middleware": "^1.0.4",
     "config": "^3.3.9",
     "cross-env": "^7.0.3",
-    "dayjs": "^1.11.9",
+    "dayjs": "^1.11.10",
     "decamelize": "^3.2.0",
     "emojic": "^1.1.17",
     "escape-string-regexp": "^4.0.0",
-    "fast-xml-parser": "^4.2.6",
-    "glob": "^10.3.3",
+    "fast-xml-parser": "^4.3.2",
+    "glob": "^10.3.10",
     "global-agent": "^3.0.0",
-    "got": "^13.0.0",
-    "graphql": "16.7.1",
+    "got": "^14.0.0",
+    "graphql": "16.8.1",
     "graphql-tag": "^2.12.6",
-    "joi": "17.9.2",
+    "joi": "17.11.0",
     "joi-extension-semver": "5.0.0",
     "js-yaml": "^4.1.0",
     "jsonpath": "~1.1.1",
@@ -56,16 +56,17 @@
     "node-pg-migrate": "^6.2.2",
     "parse-link-header": "^2.0.0",
     "path-to-regexp": "^6.2.1",
-    "pg": "^8.11.1",
+    "pg": "^8.11.3",
     "pretty-bytes": "^6.1.1",
     "priorityqueuejs": "^2.0.0",
-    "prom-client": "^14.2.0",
+    "prom-client": "^15.1.0",
     "qs": "^6.11.2",
     "query-string": "^8.1.0",
     "semver": "~7.5.4",
-    "simple-icons": "9.7.0",
+    "simple-icons": "10.4.0",
+    "smol-toml": "1.1.3",
     "webextension-store-meta": "^1.0.5",
-    "xpath": "~0.0.33"
+    "xpath": "~0.0.34"
   },
   "scripts": {
     "coverage:test:core": "c8 npm run test:core",
@@ -96,7 +97,7 @@
     "pretest": "cross-env BASE_URL=http://localhost:8080 run-s --silent defs",
     "test": "run-s --silent --continue-on-error lint test:package test:core test:entrypoint check-types:package prettier:check",
     "check-types:package": "tsd badge-maker",
-    "depcheck": "check-node-version --node \">= 16.0\"",
+    "depcheck": "check-node-version --node \">= 20.0\"",
     "prebuild": "run-s --silent depcheck",
     "defs": "node scripts/export-openapi-cli.js",
     "build": "rimraf public && run-s defs docusaurus:build",
@@ -143,77 +144,77 @@
     ]
   },
   "devDependencies": {
-    "@docusaurus/core": "^2.0.0",
-    "@easyops-cn/docusaurus-search-local": "^0.35.0",
+    "@docusaurus/core": "^2.4.3",
+    "@easyops-cn/docusaurus-search-local": "^0.40.1",
     "@mdx-js/react": "^1.6.21",
-    "@typescript-eslint/parser": "^6.2.0",
+    "@typescript-eslint/parser": "^6.16.0",
     "c8": "^8.0.1",
     "caller": "^1.1.0",
-    "chai": "^4.3.7",
+    "chai": "^4.3.10",
     "chai-as-promised": "^7.1.1",
     "chai-datetime": "^1.8.0",
     "chai-string": "^1.4.0",
     "child-process-promise": "^2.2.1",
     "clsx": "^2.0.0",
-    "concurrently": "^8.2.0",
-    "cypress": "^12.17.2",
+    "concurrently": "^8.2.2",
+    "cypress": "^13.6.2",
     "cypress-wait-for-stable-dom": "^0.1.0",
-    "danger": "^11.2.7",
+    "danger": "^11.3.1",
     "deepmerge": "^4.3.1",
     "docusaurus-preset-openapi": "0.6.4",
-    "eslint": "8.45.0",
-    "eslint-config-prettier": "^8.9.0",
+    "eslint": "8.56.0",
+    "eslint-config-prettier": "^9.1.0",
     "eslint-config-standard": "17.1.0",
     "eslint-config-standard-jsx": "11.0.0",
     "eslint-config-standard-react": "13.0.0",
     "eslint-plugin-chai-friendly": "^0.7.2",
-    "eslint-plugin-cypress": "^2.13.3",
+    "eslint-plugin-cypress": "^2.15.1",
     "eslint-plugin-icedfrisby": "^0.1.0",
-    "eslint-plugin-import": "^2.28.0",
-    "eslint-plugin-jsdoc": "^46.4.5",
-    "eslint-plugin-mocha": "^10.1.0",
+    "eslint-plugin-import": "^2.29.1",
+    "eslint-plugin-jsdoc": "^46.9.1",
+    "eslint-plugin-mocha": "^10.2.0",
     "eslint-plugin-no-extension-in-require": "^0.2.0",
     "eslint-plugin-node": "^11.1.0",
     "eslint-plugin-promise": "6.1.1",
-    "eslint-plugin-react": "^7.33.0",
+    "eslint-plugin-react": "^7.33.2",
     "eslint-plugin-react-hooks": "^4.6.0",
-    "eslint-plugin-sort-class-members": "^1.18.0",
+    "eslint-plugin-sort-class-members": "^1.19.0",
     "form-data": "^4.0.0",
     "icedfrisby": "4.0.0",
     "icedfrisby-nock": "^2.1.0",
     "is-svg": "^5.0.0",
     "jsdoc": "^4.0.2",
-    "lint-staged": "^13.2.3",
+    "lint-staged": "^15.2.0",
     "lodash.difference": "^4.5.0",
     "minimist": "^1.2.8",
     "mocha": "^10.2.0",
     "mocha-env-reporter": "^4.0.0",
     "mocha-junit-reporter": "^2.2.1",
     "mocha-yaml-loader": "^1.0.3",
-    "nock": "13.3.2",
-    "node-mocks-http": "^1.12.2",
-    "nodemon": "^3.0.1",
+    "nock": "13.4.0",
+    "node-mocks-http": "^1.14.0",
+    "nodemon": "^3.0.2",
     "npm-run-all": "^4.1.5",
-    "open-cli": "^7.2.0",
+    "open-cli": "^8.0.0",
     "portfinder": "^1.0.32",
-    "prettier": "3.0.0",
-    "prism-react-renderer": "^2.0.6",
+    "prettier": "3.1.1",
+    "prism-react-renderer": "^2.3.1",
     "react": "^17.0.2",
     "react-dom": "^17.0.2",
     "read-all-stdin-sync": "^1.0.5",
-    "rimraf": "^5.0.1",
+    "rimraf": "^5.0.5",
     "sazerac": "^2.0.0",
     "simple-git-hooks": "^2.9.0",
-    "sinon": "^15.2.0",
+    "sinon": "^17.0.1",
     "sinon-chai": "^3.7.0",
     "snap-shot-it": "^7.9.10",
-    "start-server-and-test": "2.0.0",
-    "tsd": "^0.28.1",
-    "url": "^0.11.1"
+    "start-server-and-test": "2.0.3",
+    "tsd": "^0.30.1",
+    "url": "^0.11.3"
   },
   "engines": {
-    "node": "^16.13.0",
-    "npm": "^9.0.0"
+    "node": "^20.10.0",
+    "npm": "^9.0.0 || ^10.0.0"
   },
   "type": "module",
   "collective": {

services/amo/amo-base.js

@@ -2,7 +2,8 @@ import Joi from 'joi'
 import { nonNegativeInteger } from '../validators.js'
 import { BaseJsonService } from '../index.js'
 
-const keywords = ['amo', 'firefox']
+const description =
+  '[addons.mozilla.org](https://addons.mozilla.org) (AMO) publishes extensions for Mozilla Firefox'
 
 const schema = Joi.object({
   average_daily_users: nonNegativeInteger,
@@ -26,4 +27,4 @@ class BaseAmoService extends BaseJsonService {
   }
 }
 
-export { BaseAmoService, keywords }
+export { BaseAmoService, description }

services/amo/amo-downloads.service.js

@@ -1,8 +1,9 @@
 import { renderDownloadsBadge } from '../downloads.js'
 import { redirector, pathParams } from '../index.js'
-import { BaseAmoService } from './amo-base.js'
+import { BaseAmoService, description as baseDescription } from './amo-base.js'
+
+const description = `${baseDescription}
 
-const description = `
 Previously \`amo/d\` provided a “total downloads” badge. However,
 [updates to the v3 API](https://github.com/badges/shields/issues/3079)
 only give us weekly downloads. The route \`amo/d\` redirects to \`amo/dw\`.

services/amo/amo-rating.service.js

@@ -1,7 +1,7 @@
 import { starRating } from '../text-formatters.js'
 import { floorCount as floorCountColor } from '../color-formatters.js'
 import { pathParams } from '../index.js'
-import { BaseAmoService } from './amo-base.js'
+import { BaseAmoService, description } from './amo-base.js'
 
 export default class AmoRating extends BaseAmoService {
   static category = 'rating'
@@ -11,12 +11,14 @@ export default class AmoRating extends BaseAmoService {
     '/amo/rating/{addonId}': {
       get: {
         summary: 'Mozilla Add-on Rating',
+        description,
         parameters: pathParams({ name: 'addonId', example: 'dustman' }),
       },
     },
     '/amo/stars/{addonId}': {
       get: {
         summary: 'Mozilla Add-on Stars',
+        description,
         parameters: pathParams({ name: 'addonId', example: 'dustman' }),
       },
     },

services/amo/amo-users.service.js

@@ -1,6 +1,6 @@
 import { renderDownloadsBadge } from '../downloads.js'
 import { pathParams } from '../index.js'
-import { BaseAmoService } from './amo-base.js'
+import { BaseAmoService, description } from './amo-base.js'
 
 export default class AmoUsers extends BaseAmoService {
   static category = 'downloads'
@@ -10,6 +10,7 @@ export default class AmoUsers extends BaseAmoService {
     '/amo/users/{addonId}': {
       get: {
         summary: 'Mozilla Add-on Users',
+        description,
         parameters: pathParams({ name: 'addonId', example: 'dustman' }),
       },
     },

services/amo/amo-version.service.js

@@ -1,6 +1,6 @@
 import { renderVersionBadge } from '../version.js'
 import { pathParams } from '../index.js'
-import { BaseAmoService } from './amo-base.js'
+import { BaseAmoService, description } from './amo-base.js'
 
 export default class AmoVersion extends BaseAmoService {
   static category = 'version'
@@ -10,6 +10,7 @@ export default class AmoVersion extends BaseAmoService {
     '/amo/v/{addonId}': {
       get: {
         summary: 'Mozilla Add-on Version',
+        description,
         parameters: pathParams({ name: 'addonId', example: 'dustman' }),
       },
     },

services/ansible/ansible-collection.service.js

@@ -1,45 +1,11 @@
-import Joi from 'joi'
-import { BaseJsonService, pathParams } from '../index.js'
+import { deprecatedService } from '../index.js'
 
-const ansibleCollectionSchema = Joi.object({
-  name: Joi.string().required(),
-  namespace: Joi.object({
-    name: Joi.string().required(),
-  }),
-}).required()
-
-class AnsibleGalaxyCollectionName extends BaseJsonService {
-  static category = 'other'
-  static route = { base: 'ansible/collection', pattern: ':collectionId' }
-
-  static openApi = {
-    '/ansible/collection/{collectionId}': {
-      get: {
-        summary: 'Ansible Collection',
-        parameters: pathParams({ name: 'collectionId', example: '278' }),
-      },
-    },
-  }
-
-  static defaultBadgeData = { label: 'collection' }
-
-  static render({ name }) {
-    return { message: name, color: 'blue' }
-  }
-
-  async fetch({ collectionId }) {
-    const url = `https://galaxy.ansible.com/api/v2/collections/${collectionId}/`
-    return this._requestJson({
-      url,
-      schema: ansibleCollectionSchema,
-    })
-  }
-
-  async handle({ collectionId }) {
-    const json = await this.fetch({ collectionId })
-    const name = `${json.namespace.name}.${json.name}`
-    return this.constructor.render({ name })
-  }
-}
-
-export { AnsibleGalaxyCollectionName }
+export const AnsibleGalaxyCollectionName = deprecatedService({
+  category: 'other',
+  route: {
+    base: 'ansible/collection',
+    pattern: ':collectionId',
+  },
+  label: 'collection',
+  dateAdded: new Date('2023-10-10'),
+})

services/ansible/ansible-collection.tester.js

@@ -1,14 +1,10 @@
 import { ServiceTester } from '../tester.js'
 export const t = new ServiceTester({
-  id: 'AnsibleCollection',
-  title: 'AnsibleCollection',
+  id: 'AnsibleGalaxyCollectionName',
+  title: 'AnsibleGalaxyCollectionName',
   pathPrefix: '/ansible/collection',
 })
 
-t.create('collection name (valid)')
+t.create('collection name')
   .get('/278.json')
-  .expectBadge({ label: 'collection', message: 'community.general' })
-
-t.create('collection name (not found)')
-  .get('/000.json')
-  .expectBadge({ label: 'collection', message: 'not found' })
+  .expectBadge({ label: 'collection', message: 'no longer available' })

services/ansible/ansible-quality.service.js

@@ -1,52 +1,11 @@
-import Joi from 'joi'
-import { floorCount } from '../color-formatters.js'
-import { BaseJsonService, InvalidResponse, pathParams } from '../index.js'
+import { deprecatedService } from '../index.js'
 
-const ansibleContentSchema = Joi.object({
-  quality_score: Joi.number().allow(null).required(),
-}).required()
-
-class AnsibleGalaxyContent extends BaseJsonService {
-  async fetch({ projectId }) {
-    const url = `https://galaxy.ansible.com/api/v1/content/${projectId}/`
-    return this._requestJson({
-      url,
-      schema: ansibleContentSchema,
-    })
-  }
-}
-
-export default class AnsibleGalaxyContentQualityScore extends AnsibleGalaxyContent {
-  static category = 'analysis'
-  static route = { base: 'ansible/quality', pattern: ':projectId' }
-
-  static openApi = {
-    '/ansible/quality/{projectId}': {
-      get: {
-        summary: 'Ansible Quality Score',
-        parameters: pathParams({ name: 'projectId', example: '432' }),
-      },
-    },
-  }
-
-  static defaultBadgeData = { label: 'quality' }
-
-  static render({ qualityScore }) {
-    return {
-      message: qualityScore,
-      color: floorCount(qualityScore, 2, 3, 4),
-    }
-  }
-
-  async handle({ projectId }) {
-    const { quality_score: qualityScore } = await this.fetch({ projectId })
-
-    if (qualityScore === null) {
-      throw new InvalidResponse({
-        prettyMessage: 'no score available',
-      })
-    }
-
-    return this.constructor.render({ qualityScore })
-  }
-}
+export const AnsibleGalaxyContentQualityScore = deprecatedService({
+  category: 'analysis',
+  route: {
+    base: 'ansible/quality',
+    pattern: ':projectId',
+  },
+  label: 'quality',
+  dateAdded: new Date('2023-10-10'),
+})

services/ansible/ansible-quality.tester.js

@@ -1,15 +1,10 @@
-import { nonNegativeInteger } from '../validators.js'
-import { createServiceTester } from '../tester.js'
-export const t = await createServiceTester()
+import { ServiceTester } from '../tester.js'
+export const t = new ServiceTester({
+  id: 'AnsibleGalaxyContentQualityScore',
+  title: 'AnsibleGalaxyContentQualityScore',
+  pathPrefix: '/ansible/quality',
+})
 
-t.create('quality score (valid)')
+t.create('quality score')
   .get('/432.json')
-  .expectBadge({ label: 'quality', message: nonNegativeInteger })
-
-t.create('quality score (project not found)')
-  .get('/0101.json')
-  .expectBadge({ label: 'quality', message: 'not found' })
-
-t.create('quality score (no score available)')
-  .get('/2504.json')
-  .expectBadge({ label: 'quality', message: 'no score available' })
+  .expectBadge({ label: 'quality', message: 'no longer available' })

services/ansible/ansible-role.service.js

@@ -1,73 +1,83 @@
 import Joi from 'joi'
 import { renderDownloadsBadge } from '../downloads.js'
 import { nonNegativeInteger } from '../validators.js'
-import { BaseJsonService, pathParams } from '../index.js'
+import {
+  BaseJsonService,
+  deprecatedService,
+  NotFound,
+  pathParams,
+} from '../index.js'
 
 const ansibleRoleSchema = Joi.object({
-  download_count: nonNegativeInteger,
-  name: Joi.string().required(),
-  summary_fields: Joi.object({
-    namespace: Joi.object({
-      name: Joi.string().required(),
-    }),
-  }),
+  results: Joi.array()
+    .items(
+      Joi.object({
+        download_count: nonNegativeInteger,
+      }),
+    )
+    .required(),
 }).required()
 
-class AnsibleGalaxyRole extends BaseJsonService {
-  async fetch({ roleId }) {
-    const url = `https://galaxy.ansible.com/api/v1/roles/${roleId}/`
-    return this._requestJson({
-      url,
-      schema: ansibleRoleSchema,
-    })
-  }
-}
+const AnsibleGalaxyRoleName = deprecatedService({
+  name: 'DeprecatedAnsibleGalaxyRoleName',
+  category: 'other',
+  route: {
+    base: 'ansible/role',
+    pattern: ':roleId',
+  },
+  label: 'role',
+  dateAdded: new Date('2023-10-10'),
+})
 
-class AnsibleGalaxyRoleDownloads extends AnsibleGalaxyRole {
+const AnsibleGalaxyRoleLegacyDownloads = deprecatedService({
+  name: 'DeprecatedAnsibleGalaxyRoleDownloads',
+  category: 'downloads',
+  route: {
+    base: 'ansible/role/d',
+    pattern: ':roleId',
+  },
+  label: 'role downloads',
+  dateAdded: new Date('2023-10-10'),
+})
+
+class AnsibleGalaxyRoleDownloads extends BaseJsonService {
   static category = 'downloads'
-  static route = { base: 'ansible/role/d', pattern: ':roleId' }
+  static route = { base: 'ansible/role/d', pattern: ':namespace/:name' }
 
   static openApi = {
-    '/ansible/role/d/{roleId}': {
+    '/ansible/role/d/{namespace}/{name}': {
       get: {
         summary: 'Ansible Role',
-        parameters: pathParams({ name: 'roleId', example: '3078' }),
+        parameters: pathParams(
+          { name: 'namespace', example: 'openwisp' },
+          { name: 'name', example: 'openwisp2' },
+        ),
       },
     },
   }
 
   static defaultBadgeData = { label: 'role downloads' }
 
-  async handle({ roleId }) {
-    const json = await this.fetch({ roleId })
-    return renderDownloadsBadge({ downloads: json.download_count })
+  async fetch({ namespace, name }) {
+    const url = 'https://galaxy.ansible.com/api/v1/roles/'
+    return this._requestJson({
+      url,
+      schema: ansibleRoleSchema,
+      options: { searchParams: { namespace, name, limit: 1 } },
+    })
+  }
+
+  async handle({ namespace, name }) {
+    const json = await this.fetch({ namespace, name })
+    if (json.results.length === 0) {
+      throw new NotFound({ prettyMessage: 'not found' })
+    }
+    return renderDownloadsBadge({ downloads: json.results[0].download_count })
   }
 }
 
-class AnsibleGalaxyRoleName extends AnsibleGalaxyRole {
-  static category = 'other'
-  static route = { base: 'ansible/role', pattern: ':roleId' }
-
-  static openApi = {
-    '/ansible/role/{roleId}': {
-      get: {
-        summary: 'Ansible Galaxy Role Name',
-        parameters: pathParams({ name: 'roleId', example: '3078' }),
-      },
-    },
-  }
-
-  static defaultBadgeData = { label: 'role' }
-
-  static render({ name }) {
-    return { message: name, color: 'blue' }
-  }
-
-  async handle({ roleId }) {
-    const json = await this.fetch({ roleId })
-    const name = `${json.summary_fields.namespace.name}.${json.name}`
-    return this.constructor.render({ name })
-  }
+export {
+  AnsibleGalaxyRoleDownloads,
+  AnsibleGalaxyRoleName,
+  AnsibleGalaxyRoleLegacyDownloads,
 }
-
-export { AnsibleGalaxyRoleDownloads, AnsibleGalaxyRoleName }

services/ansible/ansible-role.tester.js

@@ -1,23 +1,23 @@
 import { isMetric } from '../test-validators.js'
 import { ServiceTester } from '../tester.js'
 export const t = new ServiceTester({
-  id: 'AnsibleRole',
-  title: 'AnsibleRole',
+  id: 'AnsibleGalaxyRole',
+  title: 'AnsibleGalaxyRole',
   pathPrefix: '/ansible/role',
 })
 
-t.create('role name (valid)')
+t.create('role name')
   .get('/14542.json')
-  .expectBadge({ label: 'role', message: 'openwisp.openwisp2' })
+  .expectBadge({ label: 'role', message: 'no longer available' })
 
-t.create('role name (not found)')
-  .get('/000.json')
-  .expectBadge({ label: 'role', message: 'not found' })
+t.create('role downloads (deprecated)')
+  .get('/d/14542.json')
+  .expectBadge({ label: 'role downloads', message: 'no longer available' })
 
 t.create('role downloads (valid)')
-  .get('/d/14542.json')
+  .get('/d/openwisp/openwisp2.json')
   .expectBadge({ label: 'role downloads', message: isMetric })
 
 t.create('role downloads (not found)')
-  .get('/d/does-not-exist.json')
+  .get('/d/does-not/exist.json')
   .expectBadge({ label: 'role downloads', message: 'not found' })

services/archlinux/archlinux.service.js

@@ -1,6 +1,6 @@
 import Joi from 'joi'
 import { renderVersionBadge } from '../version.js'
-import { BaseJsonService } from '../index.js'
+import { BaseJsonService, pathParams } from '../index.js'
 
 const schema = Joi.object({
   pkgver: Joi.string().required(),
@@ -13,17 +13,27 @@ export default class ArchLinux extends BaseJsonService {
     pattern: ':repository/:architecture/:packageName',
   }
 
-  static examples = [
-    {
-      title: 'Arch Linux package',
-      namedParams: {
-        architecture: 'x86_64',
-        repository: 'core',
-        packageName: 'pacman',
+  static openApi = {
+    '/archlinux/v/{repository}/{architecture}/{packageName}': {
+      get: {
+        summary: 'Arch Linux package',
+        parameters: pathParams(
+          {
+            name: 'repository',
+            example: 'core',
+          },
+          {
+            name: 'architecture',
+            example: 'x86_64',
+          },
+          {
+            name: 'packageName',
+            example: 'pacman',
+          },
+        ),
       },
-      staticPreview: renderVersionBadge({ version: '5.1.3' }),
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'arch linux' }
 

services/aur/aur.service.js

@@ -6,7 +6,12 @@ import {
 import { renderLicenseBadge } from '../licenses.js'
 import { addv, metric, formatDate } from '../text-formatters.js'
 import { nonNegativeInteger } from '../validators.js'
-import { BaseJsonService, NotFound, InvalidResponse } from '../index.js'
+import {
+  BaseJsonService,
+  NotFound,
+  InvalidResponse,
+  pathParams,
+} from '../index.js'
 
 const aurSchema = Joi.object({
   resultcount: nonNegativeInteger,
@@ -52,13 +57,18 @@ class AurLicense extends BaseAurService {
   static category = 'license'
   static route = { base: 'aur/license', pattern: ':packageName' }
 
-  static examples = [
-    {
-      title: 'AUR license',
-      namedParams: { packageName: 'android-studio' },
-      staticPreview: renderLicenseBadge({ license: 'Apache', color: 'blue' }),
+  static openApi = {
+    '/aur/license/{packageName}': {
+      get: {
+        summary: 'AUR License',
+        description: 'Arch linux User Repository License',
+        parameters: pathParams({
+          name: 'packageName',
+          example: 'android-studio',
+        }),
+      },
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'license' }
 
@@ -83,13 +93,15 @@ class AurVotes extends BaseAurService {
 
   static route = { base: 'aur/votes', pattern: ':packageName' }
 
-  static examples = [
-    {
-      title: 'AUR votes',
-      namedParams: { packageName: 'dropbox' },
-      staticPreview: this.render({ votes: '2280' }),
+  static openApi = {
+    '/aur/votes/{packageName}': {
+      get: {
+        summary: 'AUR Votes',
+        description: 'Arch linux User Repository Votes',
+        parameters: pathParams({ name: 'packageName', example: 'dropbox' }),
+      },
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'votes' }
 
@@ -109,13 +121,19 @@ class AurVotes extends BaseAurService {
 class AurVersion extends BaseAurService {
   static category = 'version'
   static route = { base: 'aur/version', pattern: ':packageName' }
-  static examples = [
-    {
-      title: 'AUR version',
-      namedParams: { packageName: 'visual-studio-code-bin' },
-      staticPreview: this.render({ version: '1.34.0-2', outOfDate: null }),
+
+  static openApi = {
+    '/aur/version/{packageName}': {
+      get: {
+        summary: 'AUR Version',
+        description: 'Arch linux User Repository Version',
+        parameters: pathParams({
+          name: 'packageName',
+          example: 'visual-studio-code-bin',
+        }),
+      },
     },
-  ]
+  }
 
   static _cacheLength = 3600
 
@@ -140,13 +158,18 @@ class AurMaintainer extends BaseAurService {
 
   static route = { base: 'aur/maintainer', pattern: ':packageName' }
 
-  static examples = [
-    {
-      title: 'AUR maintainer',
-      namedParams: { packageName: 'google-chrome' },
-      staticPreview: this.render({ maintainer: 'luzifer' }),
+  static openApi = {
+    '/aur/maintainer/{packageName}': {
+      get: {
+        summary: 'AUR Maintainer',
+        description: 'Arch linux User Repository Maintainer',
+        parameters: pathParams({
+          name: 'packageName',
+          example: 'google-chrome',
+        }),
+      },
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'maintainer', color: 'blue' }
 
@@ -173,13 +196,18 @@ class AurLastModified extends BaseAurService {
     pattern: ':packageName',
   }
 
-  static examples = [
-    {
-      title: 'AUR last modified',
-      namedParams: { packageName: 'google-chrome' },
-      staticPreview: this.render({ date: new Date().getTime() }),
+  static openApi = {
+    '/aur/last-modified/{packageName}': {
+      get: {
+        summary: 'AUR Last Modified',
+        description: 'Arch linux User Repository Last Modified',
+        parameters: pathParams({
+          name: 'packageName',
+          example: 'google-chrome',
+        }),
+      },
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'last modified' }
 

services/aur/aur.tester.js

@@ -75,7 +75,7 @@ t.create('license (package not found)')
 
 t.create('maintainer (valid)')
   .get('/maintainer/google-chrome.json')
-  .expectBadge({ label: 'maintainer', message: 'luzifer' })
+  .expectBadge({ label: 'maintainer', message: 'gromit' })
 
 t.create('maintainer (not found)')
   .get('/maintainer/not-a-package.json')

services/azure-devops/azure-devops-build.service.js

@@ -1,14 +1,21 @@
 import Joi from 'joi'
 import { renderBuildStatusBadge } from '../build-status.js'
-import { BaseSvgScrapingService, NotFound } from '../index.js'
-import { keywords, fetch } from './azure-devops-helpers.js'
+import {
+  BaseSvgScrapingService,
+  NotFound,
+  queryParam,
+  pathParam,
+} from '../index.js'
+import { fetch } from './azure-devops-helpers.js'
 
 const queryParamSchema = Joi.object({
   stage: Joi.string(),
   job: Joi.string(),
 })
 
-const documentation = `
+const description = `
+[Azure Devops](https://dev.azure.com/) (formerly VSO, VSTS) is Microsoft Azure's CI/CD platform.
+
 A badge requires three pieces of information:
 \`ORGANIZATION\`, \`PROJECT_ID\` and \`DEFINITION_ID\`.
 
@@ -37,62 +44,68 @@ export default class AzureDevOpsBuild extends BaseSvgScrapingService {
     queryParamSchema,
   }
 
-  static examples = [
-    {
-      title: 'Azure DevOps builds',
-      pattern: ':organization/:projectId/:definitionId',
-      namedParams: {
-        organization: 'totodem',
-        projectId: '8cf3ec0e-d0c2-4fcd-8206-ad204f254a96',
-        definitionId: '2',
+  static openApi = {
+    '/azure-devops/build/{organization}/{projectId}/{definitionId}': {
+      get: {
+        summary: 'Azure DevOps builds',
+        description,
+        parameters: [
+          pathParam({
+            name: 'organization',
+            example: 'totodem',
+          }),
+          pathParam({
+            name: 'projectId',
+            example: '8cf3ec0e-d0c2-4fcd-8206-ad204f254a96',
+          }),
+          pathParam({
+            name: 'definitionId',
+            example: '2',
+          }),
+          queryParam({
+            name: 'stage',
+            example: 'Successful Stage',
+          }),
+          queryParam({
+            name: 'job',
+            example: 'Successful Job',
+          }),
+        ],
       },
-      staticPreview: renderBuildStatusBadge({ status: 'succeeded' }),
-      keywords,
-      documentation,
     },
-    {
-      title: 'Azure DevOps builds (branch)',
-      pattern: ':organization/:projectId/:definitionId/:branch',
-      namedParams: {
-        organization: 'totodem',
-        projectId: '8cf3ec0e-d0c2-4fcd-8206-ad204f254a96',
-        definitionId: '2',
-        branch: 'master',
+    '/azure-devops/build/{organization}/{projectId}/{definitionId}/{branch}': {
+      get: {
+        summary: 'Azure DevOps builds (branch)',
+        description,
+        parameters: [
+          pathParam({
+            name: 'organization',
+            example: 'totodem',
+          }),
+          pathParam({
+            name: 'projectId',
+            example: '8cf3ec0e-d0c2-4fcd-8206-ad204f254a96',
+          }),
+          pathParam({
+            name: 'definitionId',
+            example: '2',
+          }),
+          pathParam({
+            name: 'branch',
+            example: 'master',
+          }),
+          queryParam({
+            name: 'stage',
+            example: 'Successful Stage',
+          }),
+          queryParam({
+            name: 'job',
+            example: 'Successful Job',
+          }),
+        ],
       },
-      staticPreview: renderBuildStatusBadge({ status: 'succeeded' }),
-      keywords,
-      documentation,
     },
-    {
-      title: 'Azure DevOps builds (stage)',
-      namedParams: {
-        organization: 'totodem',
-        projectId: '8cf3ec0e-d0c2-4fcd-8206-ad204f254a96',
-        definitionId: '5',
-      },
-      queryParams: {
-        stage: 'Successful Stage',
-      },
-      staticPreview: renderBuildStatusBadge({ status: 'succeeded' }),
-      keywords,
-      documentation,
-    },
-    {
-      title: 'Azure DevOps builds (job)',
-      namedParams: {
-        organization: 'totodem',
-        projectId: '8cf3ec0e-d0c2-4fcd-8206-ad204f254a96',
-        definitionId: '5',
-      },
-      queryParams: {
-        stage: 'Successful Stage',
-        job: 'Successful Job',
-      },
-      staticPreview: renderBuildStatusBadge({ status: 'succeeded' }),
-      keywords,
-      documentation,
-    },
-  ]
+  }
 
   async handle(
     { organization, projectId, definitionId, branch },

services/azure-devops/azure-devops-coverage.service.js

@@ -1,9 +1,11 @@
 import Joi from 'joi'
+import { pathParams } from '../index.js'
 import { coveragePercentage as coveragePercentageColor } from '../color-formatters.js'
 import AzureDevOpsBase from './azure-devops-base.js'
-import { keywords } from './azure-devops-helpers.js'
 
-const documentation = `
+const description = `
+[Azure Devops](https://dev.azure.com/) (formerly VSO, VSTS) is Microsoft Azure's CI/CD platform.
+
 To obtain your own badge, you need to get 3 pieces of information:
 \`ORGANIZATION\`, \`PROJECT_ID\` and \`DEFINITION_ID\`.
 
@@ -47,33 +49,52 @@ export default class AzureDevOpsCoverage extends AzureDevOpsBase {
     pattern: ':organization/:project/:definitionId/:branch*',
   }
 
-  static examples = [
-    {
-      title: 'Azure DevOps coverage',
-      pattern: ':organization/:project/:definitionId',
-      namedParams: {
-        organization: 'swellaby',
-        project: 'opensource',
-        definitionId: '25',
+  static openApi = {
+    '/azure-devops/coverage/{organization}/{project}/{definitionId}': {
+      get: {
+        summary: 'Azure DevOps coverage',
+        description,
+        parameters: pathParams(
+          {
+            name: 'organization',
+            example: 'swellaby',
+          },
+          {
+            name: 'project',
+            example: 'opensource',
+          },
+          {
+            name: 'definitionId',
+            example: '25',
+          },
+        ),
       },
-      staticPreview: this.render({ coverage: 100 }),
-      keywords,
-      documentation,
     },
-    {
-      title: 'Azure DevOps coverage (branch)',
-      pattern: ':organization/:project/:definitionId/:branch',
-      namedParams: {
-        organization: 'swellaby',
-        project: 'opensource',
-        definitionId: '25',
-        branch: 'master',
+    '/azure-devops/coverage/{organization}/{project}/{definitionId}/{branch}': {
+      get: {
+        summary: 'Azure DevOps coverage (branch)',
+        description,
+        parameters: pathParams(
+          {
+            name: 'organization',
+            example: 'swellaby',
+          },
+          {
+            name: 'project',
+            example: 'opensource',
+          },
+          {
+            name: 'definitionId',
+            example: '25',
+          },
+          {
+            name: 'branch',
+            example: 'master',
+          },
+        ),
       },
-      staticPreview: this.render({ coverage: 100 }),
-      keywords,
-      documentation,
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'coverage' }
 

services/azure-devops/azure-devops-helpers.js

@@ -1,8 +1,6 @@
 import Joi from 'joi'
 import { isBuildStatus } from '../build-status.js'
 
-const keywords = ['vso', 'vsts', 'azure-devops']
-
 const schema = Joi.object({
   message: Joi.alternatives()
     .try(
@@ -26,4 +24,4 @@ async function fetch(serviceInstance, { url, searchParams = {}, httpErrors }) {
   return { status }
 }
 
-export { keywords, fetch }
+export { fetch }

services/azure-devops/azure-devops-release.service.js

@@ -1,8 +1,8 @@
 import { renderBuildStatusBadge } from '../build-status.js'
-import { BaseSvgScrapingService } from '../index.js'
-import { keywords, fetch } from './azure-devops-helpers.js'
+import { BaseSvgScrapingService, pathParams } from '../index.js'
+import { fetch } from './azure-devops-helpers.js'
 
-const documentation = `
+const description = `
 To obtain your own badge, you need to get 4 pieces of information:
 \`ORGANIZATION\`, \`PROJECT_ID\`, \`DEFINITION_ID\` and \`ENVIRONMENT_ID\`.
 
@@ -25,20 +25,33 @@ export default class AzureDevOpsRelease extends BaseSvgScrapingService {
     pattern: ':organization/:projectId/:definitionId/:environmentId',
   }
 
-  static examples = [
-    {
-      title: 'Azure DevOps releases',
-      namedParams: {
-        organization: 'totodem',
-        projectId: '8cf3ec0e-d0c2-4fcd-8206-ad204f254a96',
-        definitionId: '1',
-        environmentId: '1',
+  static openApi = {
+    '/azure-devops/release/{organization}/{projectId}/{definitionId}/{environmentId}':
+      {
+        get: {
+          summary: 'Azure DevOps releases',
+          description,
+          parameters: pathParams(
+            {
+              name: 'organization',
+              example: 'totodem',
+            },
+            {
+              name: 'projectId',
+              example: '8cf3ec0e-d0c2-4fcd-8206-ad204f254a96',
+            },
+            {
+              name: 'definitionId',
+              example: '1',
+            },
+            {
+              name: 'environmentId',
+              example: '1',
+            },
+          ),
+        },
       },
-      staticPreview: renderBuildStatusBadge({ status: 'succeeded' }),
-      keywords,
-      documentation,
-    },
-  ]
+  }
 
   static defaultBadgeData = { label: 'deployment' }
 

services/azure-devops/azure-devops-tests.service.js

@@ -1,28 +1,18 @@
 import Joi from 'joi'
+import { pathParam } from '../index.js'
 import {
+  testResultOpenApiQueryParams,
   testResultQueryParamSchema,
   renderTestResultBadge,
   documentation as commonDocumentation,
 } from '../test-results.js'
 import AzureDevOpsBase from './azure-devops-base.js'
 
-const commonAttrs = {
-  keywords: ['vso', 'vsts', 'azure-devops'],
-  namedParams: {
-    organization: 'azuredevops-powershell',
-    project: 'azuredevops-powershell',
-    definitionId: '1',
-    branch: 'master',
-  },
-  queryParams: {
-    passed_label: 'passed',
-    failed_label: 'failed',
-    skipped_label: 'skipped',
-    compact_message: null,
-  },
-  documentation: `
+const description = `
+[Azure Devops](https://dev.azure.com/) (formerly VSO, VSTS) is Microsoft Azure's CI/CD platform.
+
 To obtain your own badge, you need to get 3 pieces of information:
-\`ORGANIZATION\`, \`PROJECT_ID\`, \`DEFINITION_ID\`.
+\`ORGANIZATION\`, \`PROJECT\`, \`DEFINITION_ID\`.
 
 First, you need to select your build definition and look at the url:
 
@@ -37,8 +27,7 @@ Optionally, you can specify a named branch:
 \`https://img.shields.io/azure-devops/tests/ORGANIZATION/PROJECT/DEFINITION_ID/NAMED_BRANCH.svg\`.
 
 ${commonDocumentation}
-`,
-}
+`
 
 const buildTestResultSummarySchema = Joi.object({
   aggregatedResultsAnalysis: Joi.object({
@@ -65,48 +54,54 @@ export default class AzureDevOpsTests extends AzureDevOpsBase {
     queryParamSchema: testResultQueryParamSchema,
   }
 
-  static examples = [
-    {
-      title: 'Azure DevOps tests',
-      staticPreview: this.render({
-        passed: 20,
-        failed: 1,
-        skipped: 1,
-        total: 22,
-      }),
-      ...commonAttrs,
-    },
-    {
-      title: 'Azure DevOps tests (compact)',
-      staticPreview: this.render({
-        passed: 20,
-        failed: 1,
-        skipped: 1,
-        total: 22,
-        isCompact: true,
-      }),
-      ...commonAttrs,
-    },
-    {
-      title: 'Azure DevOps tests with custom labels',
-      queryParams: {
-        passed_label: 'good',
-        failed_label: 'bad',
-        skipped_label: 'n/a',
-        compact_message: null,
+  static openApi = {
+    '/azure-devops/tests/{organization}/{project}/{definitionId}': {
+      get: {
+        summary: 'Azure DevOps tests',
+        description,
+        parameters: [
+          pathParam({
+            name: 'organization',
+            example: 'azuredevops-powershell',
+          }),
+          pathParam({
+            name: 'project',
+            example: 'azuredevops-powershell',
+          }),
+          pathParam({
+            name: 'definitionId',
+            example: '1',
+          }),
+          ...testResultOpenApiQueryParams,
+        ],
       },
-      staticPreview: this.render({
-        passed: 20,
-        failed: 1,
-        skipped: 1,
-        total: 22,
-        passedLabel: 'good',
-        failedLabel: 'bad',
-        skippedLabel: 'n/a',
-      }),
-      ...commonAttrs,
     },
-  ]
+    '/azure-devops/tests/{organization}/{project}/{definitionId}/{branch}': {
+      get: {
+        summary: 'Azure DevOps tests (branch)',
+        description,
+        parameters: [
+          pathParam({
+            name: 'organization',
+            example: 'azuredevops-powershell',
+          }),
+          pathParam({
+            name: 'project',
+            example: 'azuredevops-powershell',
+          }),
+          pathParam({
+            name: 'definitionId',
+            example: '1',
+          }),
+          pathParam({
+            name: 'branch',
+            example: 'master',
+          }),
+          ...testResultOpenApiQueryParams,
+        ],
+      },
+    },
+  }
 
   static defaultBadgeData = { label: 'tests' }
 

services/bit/bit-components.service.js

@@ -2,7 +2,7 @@ import Joi from 'joi'
 import { metric } from '../text-formatters.js'
 import { nonNegativeInteger } from '../validators.js'
 import { downloadCount } from '../color-formatters.js'
-import { BaseJsonService } from '../index.js'
+import { BaseJsonService, pathParams } from '../index.js'
 
 const collectionSchema = Joi.object({
   payload: Joi.object({
@@ -17,14 +17,23 @@ export default class BitComponents extends BaseJsonService {
     pattern: ':owner/:collection',
   }
 
-  static examples = [
-    {
-      title: 'bit',
-      namedParams: { owner: 'ramda', collection: 'ramda' },
-      staticPreview: this.render({ count: 330 }),
-      keywords: ['components'],
+  static openApi = {
+    '/bit/collection/total-components/{owner}/{collection}': {
+      get: {
+        summary: 'Bit Components',
+        parameters: pathParams(
+          {
+            name: 'owner',
+            example: 'ramda',
+          },
+          {
+            name: 'collection',
+            example: 'ramda',
+          },
+        ),
+      },
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'components' }
 

services/bitbucket/bitbucket-pipelines.service.js

@@ -1,6 +1,6 @@
 import Joi from 'joi'
 import { renderBuildStatusBadge } from '../build-status.js'
-import { BaseJsonService, redirector } from '../index.js'
+import { BaseJsonService, redirector, pathParams } from '../index.js'
 
 const bitbucketPipelinesSchema = Joi.object({
   values: Joi.array()
@@ -30,17 +30,27 @@ class BitbucketPipelines extends BaseJsonService {
     pattern: ':user/:repo/:branch+',
   }
 
-  static examples = [
-    {
-      title: 'Bitbucket Pipelines',
-      namedParams: {
-        user: 'atlassian',
-        repo: 'adf-builder-javascript',
-        branch: 'task/SECO-2168',
+  static openApi = {
+    '/bitbucket/pipelines/{user}/{repo}/{branch}': {
+      get: {
+        summary: 'Bitbucket Pipelines',
+        parameters: pathParams(
+          {
+            name: 'user',
+            example: 'atlassian',
+          },
+          {
+            name: 'repo',
+            example: 'adf-builder-javascript',
+          },
+          {
+            name: 'branch',
+            example: 'task/SECO-2168',
+          },
+        ),
       },
-      staticPreview: this.render({ status: 'SUCCESSFUL' }),
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'build' }
 

services/bountysource/bountysource.service.js

@@ -1,6 +1,6 @@
 import Joi from 'joi'
 import { metric } from '../text-formatters.js'
-import { BaseJsonService } from '../index.js'
+import { BaseJsonService, pathParams } from '../index.js'
 
 const schema = Joi.object({ activity_total: Joi.number().required() })
 
@@ -8,13 +8,17 @@ export default class Bountysource extends BaseJsonService {
   static category = 'funding'
   static route = { base: 'bountysource/team', pattern: ':team/activity' }
 
-  static examples = [
-    {
-      title: 'Bountysource',
-      namedParams: { team: 'mozilla-core' },
-      staticPreview: this.render({ total: 53000 }),
+  static openApi = {
+    '/bountysource/team/{team}/activity': {
+      get: {
+        summary: 'Bountysource',
+        parameters: pathParams({
+          name: 'team',
+          example: 'mozilla-core',
+        }),
+      },
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'bounties' }
 

services/bower/bower-license.service.js

@@ -1,3 +1,4 @@
+import { pathParams } from '../index.js'
 import { renderLicenseBadge } from '../licenses.js'
 import BaseBowerService from './bower-base.js'
 
@@ -5,13 +6,17 @@ export default class BowerLicense extends BaseBowerService {
   static category = 'license'
   static route = { base: 'bower/l', pattern: ':packageName' }
 
-  static examples = [
-    {
-      title: 'Bower',
-      namedParams: { packageName: 'bootstrap' },
-      staticPreview: renderLicenseBadge({ licenses: ['MIT'] }),
+  static openApi = {
+    '/bower/l/{packageName}': {
+      get: {
+        summary: 'Bower License',
+        parameters: pathParams({
+          name: 'packageName',
+          example: 'bootstrap',
+        }),
+      },
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'license' }
 

services/bower/bower-version.service.js

@@ -1,15 +1,10 @@
-import Joi from 'joi'
 import { renderVersionBadge } from '../version.js'
 import { InvalidResponse } from '../index.js'
 import BaseBowerService from './bower-base.js'
 
-const queryParamSchema = Joi.object({
-  include_prereleases: Joi.equal(''),
-}).required()
-
 export default class BowerVersion extends BaseBowerService {
   static category = 'version'
-  static route = { base: 'bower/v', pattern: ':packageName', queryParamSchema }
+  static route = { base: 'bower/v', pattern: ':packageName' }
 
   static examples = [
     {
@@ -17,20 +12,12 @@ export default class BowerVersion extends BaseBowerService {
       namedParams: { packageName: 'bootstrap' },
       staticPreview: renderVersionBadge({ version: '4.2.1' }),
     },
-    {
-      title: 'Bower Version (including pre-releases)',
-      namedParams: { packageName: 'bootstrap' },
-      queryParams: { include_prereleases: null },
-      staticPreview: renderVersionBadge({ version: '4.2.1' }),
-    },
   ]
 
   static defaultBadgeData = { label: 'bower' }
 
-  static transform(data, includePrereleases) {
-    const version = includePrereleases
-      ? data.latest_release_number
-      : data.latest_stable_release_number
+  static transform(data) {
+    const version = data.latest_release_number
 
     if (!version) {
       throw new InvalidResponse({ prettyMessage: 'no releases' })
@@ -39,10 +26,9 @@ export default class BowerVersion extends BaseBowerService {
     return version
   }
 
-  async handle({ packageName }, queryParams) {
+  async handle({ packageName }) {
     const data = await this.fetch({ packageName })
-    const includePrereleases = queryParams.include_prereleases !== undefined
-    const version = this.constructor.transform(data, includePrereleases)
+    const version = this.constructor.transform(data)
 
     return renderVersionBadge({ version })
   }

services/bower/bower-version.spec.js

@@ -8,34 +8,14 @@ import BowerVersion from './bower-version.service.js'
 
 describe('BowerVersion', function () {
   test(BowerVersion.transform, () => {
-    given(
-      {
-        latest_release_number: '2.0.0-beta',
-        latest_stable_release_number: '1.8.3',
-      },
-      false,
-    ).expect('1.8.3')
-    given(
-      {
-        latest_release_number: '2.0.0-beta',
-        latest_stable_release_number: '1.8.3',
-      },
-      true,
-    ).expect('2.0.0-beta')
+    given({
+      latest_release_number: '2.0.0-beta',
+      latest_stable_release_number: '1.8.3',
+    }).expect('2.0.0-beta')
   })
 
   it('throws `no releases` InvalidResponse if no stable version', function () {
-    expect(() =>
-      BowerVersion.transform({ latest_release_number: 'panda' }, false),
-    )
-      .to.throw(InvalidResponse)
-      .with.property('prettyMessage', 'no releases')
-  })
-
-  it('throws `no releases` InvalidResponse if no prereleases', function () {
-    expect(() =>
-      BowerVersion.transform({ latest_stable_release_number: 'penguin' }, true),
-    )
+    expect(() => BowerVersion.transform({}))
       .to.throw(InvalidResponse)
       .with.property('prettyMessage', 'no releases')
   })

services/bower/bower-version.tester.js

@@ -9,7 +9,7 @@ export const t = new ServiceTester({
   pathPrefix: '/bower',
 })
 
-t.create('version').timeout(10000).get('/v/angular.json').expectBadge({
+t.create('version').timeout(10000).get('/v/backbone.json').expectBadge({
   label: 'bower',
   message: isVPlusDottedVersionAtLeastOne,
 })

services/bstats/bstats-players.service.js

@@ -1,6 +1,6 @@
 import Joi from 'joi'
 import { metric } from '../text-formatters.js'
-import { BaseJsonService } from '../index.js'
+import { BaseJsonService, pathParams } from '../index.js'
 
 const schema = Joi.array()
   .items(Joi.array().items(Joi.number().required(), Joi.number().required()))
@@ -10,15 +10,17 @@ export default class BStatsPlayers extends BaseJsonService {
   static category = 'other'
   static route = { base: 'bstats/players', pattern: ':pluginid' }
 
-  static examples = [
-    {
-      title: 'bStats Players',
-      namedParams: {
-        pluginid: '1',
+  static openApi = {
+    '/bstats/players/{pluginid}': {
+      get: {
+        summary: 'bStats Players',
+        parameters: pathParams({
+          name: 'pluginid',
+          example: '1',
+        }),
       },
-      staticPreview: this.render({ players: 74299 }),
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'players', color: 'blue' }
 

services/bstats/bstats-servers.service.js

@@ -1,6 +1,6 @@
 import Joi from 'joi'
 import { metric } from '../text-formatters.js'
-import { BaseJsonService } from '../index.js'
+import { BaseJsonService, pathParams } from '../index.js'
 
 const schema = Joi.array()
   .items(Joi.array().items(Joi.number().required(), Joi.number().required()))
@@ -10,15 +10,17 @@ export default class BStatsServers extends BaseJsonService {
   static category = 'other'
   static route = { base: 'bstats/servers', pattern: ':pluginid' }
 
-  static examples = [
-    {
-      title: 'bStats Servers',
-      namedParams: {
-        pluginid: '1',
+  static openApi = {
+    '/bstats/servers/{pluginid}': {
+      get: {
+        summary: 'bStats Servers',
+        parameters: pathParams({
+          name: 'pluginid',
+          example: '1',
+        }),
       },
-      staticPreview: this.render({ servers: 57479 }),
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'servers', color: 'blue' }