Make Changelog stuff better overall

README.md

@@ -2,4 +2,4 @@
 
 [**osu-api-v2-js**](https://github.com/TTTaevas/osu-api-v2-js) is a JavaScript & TypeScript package that helps you interact with [osu!api (v2)](https://docs.ppy.sh).
 
-It's currently extremely unstable as it's under heavy development, but be sure to come back soon so you can find it in a more stable state with documentation!!
+While it is currently unstable as it's under pretty heavy development, documentation is available on [osu-v2.taevas.xyz](https://osu-v2.taevas.xyz/)!

lib/changelog.ts

@@ -3,10 +3,24 @@ export interface ChangelogBuild {
 	display_version: string
 	id: number
 	update_stream: UpdateStream | null
+	/**
+	 * How many users are playing on this version of the game? (if lazer/web, should be 0, lazer doesn't show such stats)
+	 */
 	users: number
+	/**
+	 * The name of the version
+	 */
 	version: string | null
+	/**
+	 * If a video is showcased on the changelog
+	 * @remarks The ID of a Youtube video is whatever comes after `/watch?v=` in its url
+	 */
+	youtube_id: string | null
 	changelog_entries?: {
 		category: string
+		/**
+		 * Can be January 1st 1970!
+		 */
 		created_at: Date | null
 		github_pull_request_id: number | null
 		github_url: string | null
@@ -16,7 +30,27 @@ export interface ChangelogBuild {
 		title: string | null
 		type: string
 		url: string | null
+		/**
+		 * Entry message in Markdown format, embedded HTML is allowed, exists only if Markdown was requested
+		 */
+		message?: string | null
+		/**
+		 * Entry message in HTML format, exists only if HTML was requested
+		 */
+		message_html?: string | null
+		github_user?: {
+			display_name: string
+			github_url: string | null
+			github_username: string | null
+			id: number | null
+			osu_username: string | null
+			user_id: number | null
+			user_url: string | null
+		}
 	}
+	/**
+	 * The ChangelogBuilds in `versions` will not have `changelog_entries` or `versions`, and `users` will be 0
+	 */
 	versions?: {
 		next: ChangelogBuild | null
 		previous: ChangelogBuild | null
@@ -29,5 +63,8 @@ export interface UpdateStream {
 	is_featured: boolean
 	name: string
 	latest_build: ChangelogBuild | null
+	/**
+	 * How many users are playing on this? (if lazer/web, should be 0, lazer doesn't show such stats)
+	 */
 	user_count: number
 }

lib/index.ts

@@ -441,31 +441,44 @@ export class API {
 	 */
 	async getBeatmapPacks(type: "standard" | "featured" | "tournament" | "loved" | "chart" | "theme" | "artist" = "standard"): Promise<BeatmapPack[]> {
 		const response = await this.request("get", "beatmaps/packs", {type})
-		return correctType(response.beatmap_packs) as BeatmapPack[]
+		return response.beatmap_packs.map((b: BeatmapPack) => correctType(b)) as BeatmapPack[]
 	}
 
 
 	// CHANGELOG STUFF
 
+	/**
+	 * Get details about the version/update/build of something related to osu!
+	 * @param stream The name of the thing related to osu!, like `lazer`, `web`, `cuttingedge`, `beta40`, `stable40`
+	 * @param build The name of the version! Usually something like `2023.1026.0` for lazer, or `20230326` for stable
+	 */
 	async getChangelogBuild(stream: string, build: string): Promise<ChangelogBuild> {
 		const response = await this.request("get", `changelog/${stream}/${build}`)
 		return correctType(response) as ChangelogBuild
 	}
 
-	async getChangelogListing(format: "html" | "markdown", options?: {build_version_range?: {from?: string, to?: string},
-	max_id: number, stream: string}): Promise<ChangelogBuild[]> {
-		const message_format = [format]
-		const from = options ? options.build_version_range ? options.build_version_range.from ? options.build_version_range.from : "" : "" : ""
-		const to = options ? options.build_version_range ? options.build_version_range.from ? options.build_version_range.from : "" : "" : ""
-		const stream = options ? options.stream ? options.stream : "" : ""
-		const max_id = options ? options.max_id ? options.max_id : "" : ""
-
-		const response = await this.request("get", `changelog`, {message_format, from, to, stream, max_id})
-		return response.builds.map((b: ChangelogBuild) => correctType(b)) as ChangelogBuild[] 
+	/**
+	 * Get up to 21 versions/updates/builds!
+	 * @param versions Get builds that were released before/after (and including) those versions (use the name of the versions, e.g. `2023.1109.0`)
+	 * @param max_id Filter out builds that have an id higher than this (this takes priority over `versions.to`)
+	 * @param stream Only get builds from a specific stream
+	 * @param message_formats Each element of `changelog_entries` will have a `message` property if `markdown`, `message_html` if `html`, defaults to both
+	 */
+	async getChangelogBuilds(versions?: {from?: string, to?: string}, max_id?: number,
+	stream?: string, message_formats: ("html" | "markdown")[] = ["html", "markdown"]): Promise<ChangelogBuild[]> {
+		const [from, to] = [versions?.from, versions?.to]
+		const response = await this.request("get", "changelog", {from, to, max_id, stream, message_formats})
+		return response.builds.map((b: ChangelogBuild) => correctType(b)) as ChangelogBuild[]
 	}
 
+	/**
+	 * An effective way to get all available streams, as well as their latest version!
+	 * @example ```ts
+	 * const names_of_streams = (await api.getChangelogStreams()).map(s => s.name)
+	 * ```
+	 */
 	async getChangelogStreams(): Promise<UpdateStream[]> {
-		const response = await this.request("get", `changelog`, {max_id: 1})
+		const response = await this.request("get", `changelog`, {max_id: 0})
 		return response.streams.map((s: UpdateStream) => correctType(s)) as UpdateStream[] 
 	}
 
@@ -551,8 +564,6 @@ export class API {
 function correctType(x: any): any {
 	if (typeof x === "boolean") {
 		return x
-	} else if (!isNaN(x)) {
-		return x === null ? null : Number(x)
 	} else if (/^[+-[0-9][0-9]+-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$/.test(x) ||
 	/^[+-[0-9][0-9]+-[0-9]{2}-[0-9]{2}$/g.test(x) || /^[+-[0-9][0-9]+-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{0,}Z$/g.test(x)) {
 		return new Date(x)
@@ -564,11 +575,13 @@ function correctType(x: any): any {
 		return new Date(x)
 	} else if (Array.isArray(x)) {
 		return x.map((e) => correctType(e))
+	} else if (!isNaN(x)) {
+		return x === null ? null : Number(x)
 	} else if (typeof x === "object" && x !== null) {
 		const k = Object.keys(x)
 		const v = Object.values(x)
 		for (let i = 0; i < k.length; i++) {
-			if (k[i] == "name") continue // don't turn names made of numbers into integers
+			if (k[i].includes("name") || k[i].includes("version")) continue // don't turn names made of numbers into integers
 			x[k[i]] = correctType(v[i])
 		}
 	}

lib/tests/test.ts

@@ -86,15 +86,30 @@ const testBeatmapStuff = async (): Promise<boolean> => {
 	return okay
 }
 
+const testChangelogStuff = async (): Promise<boolean> => {
+	let okay = true
+
+	let c1 = await <Promise<ReturnType<typeof api.getChangelogBuild> | false>>attempt("\ngetChangelogBuild: ", api.getChangelogBuild("lazer", "2023.1008.1"))
+	if (!isOk(c1, !c1 || (c1.id === 7156))) okay = false
+	let c2 = await <Promise<ReturnType<typeof api.getChangelogBuilds> | false>>attempt(
+		"getChangelogBuilds: ", api.getChangelogBuilds({from: "2023.1031.0", to: "20231102.3"}, 7184, undefined, ["markdown"]))
+	if (!isOk(c2, !c2 || (c2.length === 4))) okay = false
+	let c3 = await <Promise<ReturnType<typeof api.getChangelogStreams> | false>>attempt("getChangelogStreams: ", api.getChangelogStreams())
+	if (!isOk(c3, !c3 || (c3.length > 2))) okay = false
+
+	return okay
+}
+
 const test = async (id: string, secret: string): Promise<void> => {
 	api = await osu.API.createAsync({id: Number(id), secret}, undefined, "all")
 
 	let a = await testUserStuff()
 	let b = await testBeatmapStuff()
+	let c = await testChangelogStuff()
 
-	let test_results = [a,b].map((bool: boolean, index: number) => bool ? `${index + 1}: ✔️\n` : `${index + 1}: ❌\n`)
+	let test_results = [a,b,c].map((bool: boolean, index: number) => bool ? `${index + 1}: ✔️\n` : `${index + 1}: ❌\n`)
 	console.log("\n", ...test_results)
-	if ([a,b].indexOf(false) === -1) {
+	if ([a,b,c].indexOf(false) === -1) {
 		console.log("✔️ Looks like the test went well!")
 	} else {
 		throw new Error("❌ Something in the test went wrong...")