Nearsighted Paramecium Multiverse
    Have ideas to improve npm?Join in the discussion! »

    node-osu
    TypeScript icon, indicating that this package has built-in type declarations

    2.2.1 • Public • Published

    node-osu

    Code Climate

    Making the osu api easy to use.

    NOTE: This is for version 1.0 of the osu!api.

    Getting Started

    Get your osu api key from https://osu.ppy.sh/p/api

    Install node-osu
    yarn add node-osu / npm i node-osu

    Running tests

    Install the dev dependencies: mocha and chai

    Run yarn/npm test

    Contributing

    • Follow the rules in .eslintrc.js
    • Separate changes into different PRs
    • Prioritize backwards-compatibility

    Documentation

    Require node-osu

    const osu = require('node-osu');

    osu.Constants

    • Mods: An object containing the bitwise representation for each mod
    • URLSchemas: An object containing osu url schema generating functions
      • multiplayerMatch: Function taking <id>, [password]
      • edit: Function taking <position>, [objects]
      • channel: Function taking <name>
      • download: Function taking <id>
      • spectate: Function taking <user>
    • Beatmaps: Beatmap constants
      • approved: Get approval state from a number representation
      • genre: Get map genre from a number representation
      • language: Get map language from a number representation
      • mode: Get game mode from a number representation
    • Multiplayer: Multiplayer match constants
      • scoringType: Get a game's scoring mode from a number representation
      • teamType: Get a game's team mode from a number representation
      • team: Get a user's team from a number representation
    • AccuracyMethods: Calculate accuracy from a score's counts

    osu.Api

    All methods return a Promise.
    options refers to the url parameters listed here: https://github.com/ppy/osu-api/wiki

    Constructor

    const osuApi = new osu.Api('A3tGREAemXk213gfJJUewH9675g', {
    	// baseUrl: sets the base api url (default: https://osu.ppy.sh/api)
    	notFoundAsError: true, // Throw an error on not found instead of returning nothing. (default: true)
    	completeScores: false, // When fetching scores also fetch the beatmap they are for (Allows getting accuracy) (default: false)
    	parseNumeric: false // Parse numeric values into numbers/floats, excluding ids
    });

    apiCall(endpoint, options)

    Make an api call. Should generally not be used.

    osuApi.apiCall('/get_user', { u: 'brussell98' }).then(user => {
    	console.log(user[0].username);
    });

    getBeatmaps(options)

    Returns an array of Beatmap objects.

    osuApi.getBeatmaps({ b: '765567' }).then(beatmaps => {
    	console.log(beatmaps[0].title);
    });

    getUser(options)

    Returns an User object.

    osuApi.getUser({ u: 'brussell98' }).then(user => {
    	console.log(user.name);
    });

    getScores(options)

    Returns an array of Score objects.

    osuApi.getScores({ b: '1036655' }).then(scores => {
    	console.log(scores[0].score);
    });
    
    // or with completeScores set to true
    osuApi.getScores({ b: '1036655' }).then(scores => {
    	console.log(scores[0].score);
    	console.log(scores[0].beatmap.title);
    	console.log(scores[0].accuracy);
    });

    getUserBest(options)

    Returns an array of Score objects.

    osuApi.getUserBest({ u: 'brussell98' }).then(scores => {
    	console.log(scores[0].score);
    });
    
    // or with completeScores set to true
    osuApi.getUserBest({ u: 'brussell98' }).then(scores => {
    	console.log(scores[0].score);
    	console.log(scores[0].beatmap.title);
    	console.log(scores[0].accuracy);
    });

    getUserRecent(options)

    Returns an array of Score objects. If the user has not submitted a score in the past 24 hours, this will return as not found.

    osuApi.getUserRecent({ u: 'brussell98' }).then(scores => {
    	console.log(scores[0].score);
    });
    
    // or with completeScores set to true
    osuApi.getUserRecent({ u: 'brussell98' }).then(scores => {
    	console.log(scores[0].score);
    	console.log(scores[0].beatmap.title);
    	console.log(scores[0].accuracy);
    });

    getMatch(options)

    Returns an Match object.

    osuApi.getMatch({ mp: '25576650' }).then(match => {
    	console.log(match.name);
    });

    getReplay(options)

    Returns a replay object. Do not spam this endpoint.

    const fs = require('fs');
    osuApi.getReplay({ m: '0', b: '1337', u: 'brussell98' }).then(replay => {
    	fs.writeFile('replay.txt', replay.content);
    });

    osu.User

    User {
    	id: '7541046',
    	name: 'brussell98',
    	counts: {
    		'50': '34327',
    		'100': '393959',
    		'300': '4008334',
    		SSH: '2',
    		SS: '4',
    		SH: '14',
    		S: '379',
    		A: '1785',
    		plays: '16951'
    	},
    	scores: {
    		ranked: '8625602786',
    		total: '20612840665'
    	},
    	pp: {
    		raw: '2669.26',
    		rank: '134346',
    		countryRank: '22842'
    	},
    	country: 'US',
    	level: '99.3151',
    	accuracy: '98.3110122680664',
    	secondsPlayed: '1239538',
    	raw_joinDate: '2015-12-09 02:27:02',
    	events: [ Event {...}, ...],
    
    	// Getters
    	accuracyFormatted: String
    	joinDate: Date
    }

    osu.Event

    Event {
    	html: '<img src=\'/images/A_small.png\'/> <b><a href=\'/u/7541046\'>brussell98</a></b> achieved rank #62 on <a href=\'/b/2244449?m=1\'>Morimori Atsushi - Toono Gensou Monogatari (MRM REMIX) [Nardo\'s Futsuu]</a> (osu!taiko)',
    	beatmapId: '2244449',
    	beatmapsetId: '812992',
    	raw_date: '2020-01-04 05:02:09',
    	epicFactor: '1',
    
    	// Getters
    	date: Date
    }

    osu.Beatmap

    Beatmap {
    	id: '765567',
    	beatmapSetId: '346872',
    	hash: '49ae1a43f732d07aff8efab2b0f22bdf',
    	title: 'GATE~Sore wa Akatsuki no you ni~ (TV size)',
    	creator: 'Del05',
    	version: 'Insane',
    	source: 'GATE 自衛隊 彼の地にて、斯く戦えり',
    	artist: 'KISIDA KYODAN & THE AKEBOSI ROCKETS',
    	genre: 'Anime',
    	language: 'Japanese',
    	rating: '9.45067',
    	bpm: '200',
    	mode: 'Standard',
    	tags: [
    		'jieitai',
    		'kanochi',
    		'nite',
    		'kaku',
    		'tatakaeri',
    		'opening',
    		'kyle',
    		'y',
    		'walaowey',
    		'rory',
    		'tuka',
    		'ゲート'
    	],
    	approvalStatus: 'Ranked',
    	raw_submitDate: '2015-08-18 14:01:13',
    	raw_approvedDate: '2016-03-18 18:21:22',
    	raw_lastUpdate: '2016-03-02 15:14:22',
    	maxCombo: '549',
    	objects: {
    		normal: '213',
    		slider: '165',
    		spinner: '0'
    	},
    	difficulty: {
    		rating: '4.68783',
    		aim: '2.36005',
    		speed: '2.29552',
    		size: '4',
    		overall: '7',
    		approach: '9',
    		drain: '6'
    	},
    	length: {
    		total: '89',
    		drain: '89'
    	},
    	counts: {
    		favorites: '1127',
    		favourites: '1127',
    		plays: '1506571',
    		passes: '262113'
    	},
    	hasDownload: true,
    	hasAudio: true,
    
    	// Getters
    	submitDate: Date,
    	approvedDate: Date,
    	lastUpdate: Date
    }

    osu.Score

    Score {
    	score: '10380039',
    	user: {
    		name: 'Sarah', // null when using a getUserX method
    		id: '7777836'
    	},
    	beatmapId: null, // When using getScores() without completeScores this will be null
    	counts: {
    		'50': '0',
    		'100': '5',
    		'300': '414',
    		geki: '92',
    		katu: '5',
    		miss: '0'
    	},
    	maxCombo: '826',
    	perfect: true,
    	raw_date: '2018-09-10 22:36:08',
    	rank: 'SH',
    	pp: '240.73', // Can be null (in recent user scores for example)
    	hasReplay: true,
    	raw_mods: 88,
    	beatmap: undefined, // or `Beatmap {...}` with completeScores
    
    	// Getters
    	date: Date,
    	mods: [Constants.Mods],
    	accuracy: Number
    }

    osu.Match

    Match {
    	id: '57155016',
    	name: 'OWC2019: (United States) vs (South Korea)',
    	raw_start: '2019-12-22 02:48:47',
    	raw_end: '2019-12-22 04:29:11',
    	games: [ Game {...}, ...],
    
    	// Getters
    	start: Date,
    	end: Date
    }

    osu.Game

    Game {
    	id: '298230665',
    	raw_start: '2019-12-22 03:57:20',
    	raw_end: '2019-12-22 04:00:19',
    	beatmapId: '1656914',
    	mode: 'Standard',
    	matchType: '0', // Unknown purpose
    	scoringType: 'Score v2',
    	teamType: 'Team vs',
    	raw_mods: 64,
    	scores: [ MultiplayerScore {...}, ...] // Will be empty if in progress
    
    	// Getters
    	start: Date,
    	end: Date,
    	mods: [ 'DoubleTime' ] // Array of `Constants.Mods` required for all players
    }

    osu.MultiplayerScore

    MultiplayerScore {
    	slot: '0',
    	team: 'Red',
    	userId: '4194445',
    	score: '353891',
    	maxCombo: '710',
    	rank: null, // Not used
    	counts: {
    		'50': '27',
    		'100': '73',
    		'300': '690',
    		geki: '129',
    		katu: '38',
    		miss: '38'
    	},
    	perfect: false,
    	pass: true,
    	raw_mods: 1,
    
    	// Getters
    	mods: [ 'NoFail' ] // Array of `Constants.Mods` used by the player
    }

    Install

    npm i node-osu

    DownloadsWeekly Downloads

    5,113

    Version

    2.2.1

    License

    MIT

    Unpacked Size

    104 kB

    Total Files

    19

    Last publish

    Collaborators

    • avatar