osu-api-v2

UNOFFICIAL!

An easy way to use the osu!api v2.

Attention: This is only a prototype that is currently aimed at providing beatmap information for another project and NOT a complete implementation of this API!

ALSO: This package after version v0.0.18 makes use of a native fetch implementation which is for example provided by node since version v17.5.0 experimentally. If you use an older version or another environment be sure to include a package like whatwg-fetch that polyfills fetch if not existing.

NPM package: osu-api-v2

HTML documentation with examples and responses: GitHub pages

GitHub repository: osu-api-v2

• Getting started
  • Acquire osu! OAuth credentials
  • Use it in a Node.js project
  • Use it in a Typescript project
• Testing and Linting
  • Testing
    • Coverage
  • Linting and Formatting
• Manage npm package
  • Preview package content
  • Test package
  • Publish package

Getting started

Acquire osu! OAuth credentials

To use the osu!api v2 you need to request a temporary OAuth access token that can be acquired with the following steps:

1. Create an osu! account or log into an existing account
2. Go to the account settings
3. Scroll to the section called OAuth
4. Create a new OAuth service

Now having the OAuth credentials you have 2 possibilities to request a temporary OAuth access token:

1. Client Credentials

   By copying the client ID and client secret you can request a temporary OAuth access token:

   import osuApiV2 from "osu-api-v2"
   
   osuApiV2.oauth.clientCredentialsGrant(
       1234,                        // Replace with your value (client ID)
       "PLACEHOLDER_CLIENT_SECRET", // Replace with your value (client secret)
   ).then(oauthAccessToken => {
       console.log(oauthAccessToken)
   }).catch(console.error)

   (Example)

2. Refresh Tokens

   By setting a Application Callback URL (redirect URI) and copying the client ID and client secret you can request a temporary OAuth access token with custom OAuth scopes. This is done by creating a special URL using these inputs and then opening this URL in the browser (or redirect the user to this URL):

   import osuApiV2, { OAuthAuthorizeScope } from "osu-api-v2"
   import open from "open"
   
   const authorizeUrl = osuApiV2.oauth.authorizeRedirectUrlGenerator(
       1234,                            // Replace with your value (client ID)
       "PLACEHOLDER_CLIENT_SECRET",     // Replace with your value (client secret)
       "https://your-redirect-uri.com", // Replace with your value (redirect URI)
       [OAuthAuthorizeScope.PUBLIC, OAuthAuthorizeScope.IDENTIFY],
   )
   await open(authorizeUrl)

   The website that will open allows yourself or your user to login and manually click a button to accept access upon which the website will send a code to the redirect URI. On the server that receives this code you can then request a refresh token:

   import osuApiV2 from "osu-api-v2"
   
   const receivedCode = "PLACEHOLDER_CODE" // Replace with received value
   osuApiV2.oauth.authorizationCodeGrant(
      1234,                            // Replace with your value (client ID)
      "PLACEHOLDER_CLIENT_SECRET",     // Replace with your value (client secret)
      "https://your-redirect-uri.com", // Replace with your value (redirect URI)
      receivedCode,
   ).then((oauthAccessTokenWithRefreshToken) => {
       console.log(oauthAccessTokenWithRefreshToken)
   }).catch(console.error)

   After all of these steps you can now without repeating the previous steps request a temporary OAuth access token:

   import osuApiV2 from "osu-api-v2"
   
   osuApiV2.oauth.refreshTokenGrant(
       1234,                            // Replace with your value (client ID)
       "PLACEHOLDER_CLIENT_SECRET",     // Replace with your value (client secret)
       "https://your-redirect-uri.com", // Replace with your value (redirect URI)
       "PLACEHOLDER_REFRESH_TOKEN",     // Replace with your value (refresh token)
   ).then(oauthAccessTokenWithRefreshToken => {
       console.log(oauthAccessTokenWithRefreshToken)
   }).catch(console.error)

   You need to keep in mind that as soon as you request a temporary OAuth access token this way your current refresh token becomes useless. For the next time you want to request a temporary OAuth access token you need to use the new refresh token that is contained in the response next to the temporary OAuth access token.

   (Example)

Use it in a Node.js project

package.json:

{
    "name": "test-osu-api-v2-nodejs",
    "version": "1.0.0",
    "scripts": {
        "start": "node index.js"
    },
    "dependencies": {
        "osu-api-v2": "^0.0.75"
    }
}

index.js:

const osuApiV2 = require("osu-api-v2").default

osuApiV2.oauth.clientCredentialsGrant(
    1234,                        // Replace with your value (client ID)
    "PLACEHOLDER_CLIENT_SECRET", // Replace with your value (client secret)
).then(oauthAccessToken => {
    console.log(oauthAccessToken)
})

Run:

npm start

Use it in a Typescript project

package.json:

{
    "name": "test-osu-api-v2-typescript",
    "version": "1.0.0",
    "scripts": {
        "build": "tsc",
        "start": "node dist/index.js"
    },
    "dependencies": {
        "osu-api-v2": "^0.0.27"
    },
    "devDependencies": {
        "typescript": "^4.8.3"
    }
}

tsconfig.json:

{
    "compilerOptions": {
        "module": "CommonJS",
        "outDir": "dist",
        "moduleResolution": "Node",
        "target": "ES6"
    },
    "exclude": [
      "dist",
      "node_modules"
    ]
}

index.ts:

import osuApiV2 from "osu-api-v2"

osuApiV2.oauth.clientCredentialsGrant(
    1234,                        // Replace with your value (client ID)
    "PLACEHOLDER_CLIENT_SECRET", // Replace with your value (client secret)
).then(oauthAccessToken => {
    console.log(oauthAccessToken)
})

Run:

npm run build
npm start

Testing and Linting

Testing

The tests can be separated in 3 different categories:

1. No osu!api v2 tests

   This means these tests can be ran without any extra information but only cover a small part of the library.

   npm run test:no-osu-api-v2

2. osu!api v2 tests using custom OAuth credentials but only with client credential grants

   To run these tests you need to provide either a file called osu_api_v2_oauth_client_credentials.secret.json that contains a valid client ID and client secret (example file) or environment variables that contain this information (OSU_OAUTH_CLIENT_ID, OSU_OAUTH_CLIENT_SECRET).

   This means these tests will cover all endpoints that can be accessed via the public API scope.

   npm run test:no-refresh-token
   # Or to get the coverage
   npm run test:coverage-no-refresh-token

3. osu!api v2 tests using custom OAuth credentials with client credential grants and refresh token grants

   To run these tests you need to provide either a file called osu_api_v2_oauth_refresh_token.secret.json that contains a valid client ID, client secret, redirect URI and current refresh token (example file) or environment variables that contain this information (OSU_OAUTH_CLIENT_ID, OSU_OAUTH_CLIENT_SECRET, OSU_OAUTH_REDIRECT_URL, OSU_OAUTH_REFRESH_TOKEN). Keep in mind that at the end of the tests the refresh token (in OSU_OAUTH_REFRESH_TOKEN) would be useless but the new valid refresh token will be in the file (osu_api_v2_oauth_refresh_token.secret.json) that was automatically created/updated during running the tests!

   This means these tests will cover all endpoints, even the ones only accessible to other API scopes (of course the success of these tests depends if you have the required API scopes enabled when initially requesting the refresh token code).

   npm run test
   # Or to get the coverage
   npm run test:coverage

Coverage

To see which parts (branches and functions) of the code are covered by the tests you can run:

npm run test:coverage
# or for a smaller subset that doesn't check non public scope API endpoints
npm run test:coverage-no-refresh-token

This does the same thing as running npm run test/npm run test:no-refresh-token but tracks the test coverage.

You can see the results either in the console or by opening the created ./coverage/index.html file.

Linting and Formatting

To format and lint the source code (and automatically fix fixable problems) run:

npm run lint:fix
npm run format:fix

To only check if the source code fulfills the requirements run:

npm run lint
npm run format

Manage npm package

Preview package content

npm pack --dry-run

Test package

# Create package 'osu-api-v2-X.Y.Z.tgz'
npm pack
# Create a new project with a package.json and add the package as dependency
npm install "path/to/osu-api-v2-X.Y.Z.tgz"

Publish package

# Login to your npm account
npm login
# [Optional]: Commit all changes to the git repository
git add -A && git commit
# [Optional]: Increase the patch version of the package
#             which automatically creates a new commit
npm version patch
# Push the new package
npm publish

In the GitHub repository is also a GitHub workflow that publishes the package when pushing a new tag. Pushing a new tag can be done using the following steps:

# Commit all changes so the git working directory is clean
# Create a new version [tag] (major, minor, patch)
npm version patch
# Push the changes to GitHub
git push
# If not automatically push the created tag(s)
git push --tags
# Now the workflow should be triggered too and automatically
# publish a new version of the package to npm