@ejercito-fam/habbo-api 1.0.0

package/.yarnrc.yml

@@ -0,0 +1,5 @@
+enableGlobalCache: true
+compressionLevel: mixed
+nodeLinker: node-modules
+
+yarnPath: .yarn/releases/yarn-4.7.0.cjs

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 EjercitoFAM
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,9 @@
+# Bot
+
+## Setup
+
+To manage dependencies, it is recommended to use Yarn, using `yarn --immutable` to install dependencies.
+
+Create a `.env.development.local` file inside the `src` directory, copying the template from the `.env` file in the same
+directory, and then fill in the fields. The ENV loader is powered by
+[`@skyra/env-utilities`](https://www.npmjs.com/package/@skyra/env-utilities), more information in the package.

package/package.json

@@ -0,0 +1,45 @@
+{
+	"name": "@ejercito-fam/habbo-api",
+	"description": "A typed Habbo API library",
+	"version": "1.0.0",
+	"main": "./dist/main.js",
+	"type": "module",
+	"scripts": {
+		"start": "node ./dist/main.js",
+		"build": "tsc -b src",
+		"dev": "yarn build && yarn start",
+		"prepublishOnly": "yarn build"
+	},
+	"exports": {
+		"types": "./dist/index.d.ts",
+		"import": "./dist/index.js"
+	},
+	"dependencies": {
+		"@skyra/safe-fetch": "^1.1.3"
+	},
+	"devDependencies": {
+		"@sapphire/eslint-config": "^5.0.5",
+		"@sapphire/prettier-config": "^2.0.0",
+		"@sapphire/ts-config": "^5.0.1",
+		"@types/node": "^22.15.2",
+		"@typescript-eslint/eslint-plugin": "^8.31.0",
+		"@typescript-eslint/parser": "^8.31.0",
+		"eslint": "^9.25.1",
+		"eslint-config-prettier": "^10.1.2",
+		"eslint-plugin-prettier": "^5.2.6",
+		"prettier": "^3.5.3",
+		"typescript": "^5.8.3"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"prettier": "@sapphire/prettier-config",
+	"eslintConfig": {
+		"extends": "@sapphire",
+		"ignorePatterns": [
+			"node_modules/",
+			"dist/"
+		]
+	},
+	"packageManager": "yarn@4.7.0"
+}

package/src/constants.ts

@@ -0,0 +1,25 @@
+export enum HotelDomainTLD {
+	Brazilian = '.com.br',
+	Danish = '.dk',
+	Dutch = '.nl',
+	Finnish = '.fi',
+	French = '.fr',
+	German = '.de',
+	International = '.com',
+	Italian = '.it',
+	Spanish = '.es',
+	Turkish = '.com.tr'
+}
+
+export const HotelDomainURL = {
+	Brazilian: `https://www.habbo${HotelDomainTLD.Brazilian}`,
+	Danish: `https://www.habbo${HotelDomainTLD.Danish}`,
+	Dutch: `https://www.habbo${HotelDomainTLD.Dutch}`,
+	Finnish: `https://www.habbo${HotelDomainTLD.Finnish}`,
+	French: `https://www.habbo${HotelDomainTLD.French}`,
+	German: `https://www.habbo${HotelDomainTLD.German}`,
+	International: `https://www.habbo${HotelDomainTLD.International}`,
+	Italian: `https://www.habbo${HotelDomainTLD.Italian}`,
+	Spanish: `https://www.habbo${HotelDomainTLD.Spanish}`,
+	Turkish: `https://www.habbo${HotelDomainTLD.Turkish}`
+} as const;

package/src/habbo.ts

@@ -0,0 +1,36 @@
+import { HotelDomainURL } from 'constants.js';
+import { AchievementsAPI } from './routes/achievements.js';
+import { GroupsAPI } from './routes/groups.js';
+import { ListsAPI } from './routes/lists.js';
+import { MarketplaceAPI } from './routes/marketplace.js';
+import { PingAPI } from './routes/ping.js';
+import { RoomsAPI } from './routes/rooms.js';
+import { UsersAPI } from './routes/users.js';
+
+export class Habbo {
+	public readonly achievements: AchievementsAPI;
+	public readonly groups: GroupsAPI;
+	public readonly lists: ListsAPI;
+	public readonly marketplace: MarketplaceAPI;
+	public readonly ping: PingAPI;
+	public readonly rooms: RoomsAPI;
+	public readonly users: UsersAPI;
+
+	public constructor(options?: HabboOptions) {
+		const baseURL = options?.baseURL ?? HotelDomainURL.International;
+		const timeout = options?.timeout ?? null;
+
+		this.achievements = new AchievementsAPI(baseURL, timeout);
+		this.groups = new GroupsAPI(baseURL, timeout);
+		this.lists = new ListsAPI(baseURL, timeout);
+		this.marketplace = new MarketplaceAPI(baseURL, timeout);
+		this.ping = new PingAPI(baseURL, timeout);
+		this.rooms = new RoomsAPI(baseURL, timeout);
+		this.users = new UsersAPI(baseURL, timeout);
+	}
+}
+
+export interface HabboOptions {
+	baseURL?: string | null | undefined;
+	timeout?: number | null | undefined;
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+export * from './constants.js';
+export * from './habbo.js';
+export * from './routes/achievements.js';
+export * from './routes/groups.js';
+export * from './routes/lists.js';
+export * from './routes/marketplace.js';
+export * from './routes/ping.js';
+export * from './routes/rooms.js';
+export * from './routes/users.js';

package/src/routes/achievements.ts

@@ -0,0 +1,67 @@
+import { Json, type FetchResult } from '@skyra/safe-fetch';
+import { BaseAPI, type APIOptions } from './base.js';
+import type { HabboUserId } from './users.js';
+
+export class AchievementsAPI extends BaseAPI {
+	/**
+	 * Get all achievements
+	 *
+	 * @param options - The options for the API call
+	 */
+	public getAll(options?: APIOptions): Promise<FetchResult<Achievement[]>> {
+		const url = this.formatURL('/api/public/achievements');
+		return Json<Achievement[]>(this.fetch(url, options));
+	}
+
+	/**
+	 * Get the achievements from a specified user ID
+	 *
+	 * @param id - The ID of the user
+	 * @param options - The options for the API call
+	 */
+	public getByUserId(id: HabboUserId, options?: APIOptions): Promise<FetchResult<UserAchievement[]>> {
+		const url = this.formatURL(`/api/public/achievements/${id}`);
+		return Json<UserAchievement[]>(this.fetch(url, options));
+	}
+
+	/**
+	 * Get the image URL for an achievement
+	 *
+	 * @param achievementName - The name of the achievement, retrieved from {@linkcode AchievementData.name}
+	 *
+	 * @unstable This feature is not documented, use at your own risk
+	 */
+	public getImageURL(achievementName: string): URL {
+		return new URL(`https://images.habbo.com/c_images/album1584/${achievementName}.png`);
+	}
+}
+
+export interface Achievement {
+	achievement: AchievementData;
+	levelRequirements: AchievementRequirements;
+}
+
+export interface UserAchievement {
+	achievement: AchievementData;
+	level: number;
+	score: number;
+}
+
+export interface AchievementData {
+	id: number;
+	name: string;
+	creationTime: `${bigint}-${bigint}-${bigint}`;
+	state: AchievementDataState;
+	category: string;
+}
+
+export enum AchievementDataState {
+	Enabled = 'ENABLED',
+	Archived = 'ARCHIVED',
+	OffSeason = 'OFF_SEASON'
+}
+
+export interface AchievementRequirements {
+	level: number;
+	requiredScore: number;
+}

package/src/routes/base.ts

@@ -0,0 +1,33 @@
+import { safeFetch, type FetchResult } from '@skyra/safe-fetch';
+
+export abstract class BaseAPI {
+	protected readonly baseURL: string;
+	protected readonly timeout: number | null;
+
+	public constructor(baseURL: string, timeout?: number | null | undefined) {
+		this.baseURL = baseURL;
+		this.timeout = timeout ?? null;
+	}
+
+	protected formatURL(route: string): URL {
+		return new URL(route, this.baseURL);
+	}
+
+	protected fetch(url: string | URL, options?: APIOptions): Promise<FetchResult<Response>> {
+		return safeFetch(url, { headers: { 'Content-Type': 'application/json' }, signal: this.#getSignalOrDefault(options) });
+	}
+
+	#getSignalOrDefault(options?: APIOptions): AbortSignal | null {
+		if (typeof options === 'object' && options !== null) {
+			if (typeof options.signal === 'number') return AbortSignal.timeout(options.signal);
+			if (typeof options.signal === 'object' && options.signal !== null) return options.signal;
+		}
+
+		if (typeof this.timeout === 'number') return AbortSignal.timeout(this.timeout);
+		return null;
+	}
+}
+
+export interface APIOptions {
+	signal?: AbortSignal | number | null | undefined;
+}

package/src/routes/groups.ts

@@ -0,0 +1,139 @@
+import { Json, type FetchResult } from '@skyra/safe-fetch';
+import { BaseAPI, type APIOptions } from './base.js';
+
+export class GroupsAPI extends BaseAPI {
+	/**
+	 * Get the data for a group given its identifier
+	 *
+	 * @param id - The ID of the group
+	 * @param options - The options for the API call
+	 */
+	public getByUniqueId(id: HabboGroupId, options?: APIOptions): Promise<FetchResult<HabboGroup>> {
+		const url = this.formatURL(`/api/public/groups/${id}`);
+		return Json<HabboGroup>(this.fetch(url, options));
+	}
+
+	/**
+	 * Get the members from a group given its identifier
+	 *
+	 * @param id - The ID of the group
+	 * @param options - The options for the API call
+	 */
+	public getGroupMembers(id: HabboGroupId, options?: APIOptions): Promise<FetchResult<HabboGroupMember[]>> {
+		const url = this.formatURL(`/api/public/groups/${id}/members`);
+		return Json<HabboGroupMember[]>(this.fetch(url, options));
+	}
+
+	/**
+	 * Get the image URL for a badge
+	 *
+	 * @param badgeCode - The badge's code, retrieved from {@linkcode HabboGroup.badgeCode}
+	 *
+	 * @unstable This feature is not documented, use at your own risk
+	 */
+	public getGroupBadgeImageURL(badgeCode: string): URL {
+		return this.formatURL(`/habbo-imaging/badge/${badgeCode}`);
+	}
+}
+
+export type HabboGroupId = `g-hh${string}-${string};`
+
+/**
+ * Represents a Habbo group.
+ */
+export interface HabboGroup {
+	/**
+	 * The unique identifier of the group.
+	 */
+	id: HabboGroupId;
+
+	/**
+	 * The name of the group.
+	 */
+	name: string;
+
+	/**
+	 * The description of the group.
+	 */
+	description: string;
+
+	/**
+	 * The type of the group.
+	 */
+	type: HabboGroupType;
+
+	/**
+	 * The ID of the room associated with the group, or null if no room is associated.
+	 */
+	roomId: number | null;
+
+	/**
+	 * The badge code of the group.
+	 */
+	badgeCode: string;
+}
+
+/**
+ * Enum representing the type of a Habbo group.
+ */
+export enum HabboGroupType {
+	/**
+	 * A normal group (public).
+	 */
+	NORMAL = 'NORMAL',
+
+	/**
+	 * A favourite (exclusive) group.
+	 */
+	FAVOURITE = 'EXCLUSIVE',
+
+	/**
+	 * A private (closed) group.
+	 */
+	PRIVATE = 'CLOSED'
+}
+
+/**
+ * Represents a member of a Habbo group.
+ */
+export interface HabboGroupMember {
+	/**
+	 * Indicates whether the member is online.
+	 */
+	online: boolean;
+
+	/**
+	 * The gender of the member.
+	 */
+	gender: 'm' | 'f';
+
+	/**
+	 * The motto of the member.
+	 */
+	motto: string;
+
+	/**
+	 * The figure of the member in the Habbo world.
+	 */
+	habboFigure: string;
+
+	/**
+	 * The date since the member joined the group.
+	 */
+	memberSince: string;
+
+	/**
+	 * The unique identifier of the member.
+	 */
+	uniqueId: string;
+
+	/**
+	 * The name of the member.
+	 */
+	name: string;
+
+	/**
+	 * Indicates whether the member is an admin of the group.
+	 */
+	isAdmin: boolean;
+}

package/src/routes/lists.ts

@@ -0,0 +1,41 @@
+import { type FetchResult } from '@skyra/safe-fetch';
+import { BaseAPI, type APIOptions } from './base.js';
+
+export class ListsAPI extends BaseAPI {
+	/**
+	 * Get the hot looks from the hotel
+	 *
+	 * @param options - The options for the API call
+	 */
+	public async getHotLooks(options: APIOptions): Promise<FetchResult<HabboHotLookList>> {
+		const url = this.formatURL('/api/public/lists/hotlooks');
+		const data = await this.fetch(url, options);
+		return data.map(async (result) => this.#parseHotLooksXML(await result.text())).intoPromise();
+	}
+
+	#parseHotLooksXML(data: string): HabboHotLookList {
+		const urlResult = /url="(.*)"/.exec(data);
+		if (urlResult === null) throw new SyntaxError('Could not read hot looks');
+
+		const url = urlResult[1];
+		const entries = [] as HabboHotLookListItem[];
+		for (const result of data.matchAll(/gender="(\w)" figure="(.+)" hash="(.+)"/g)) {
+			entries.push({ gender: result[1] as 'f' | 'm', figure: result[2], hash: result[3] });
+		}
+
+		if (entries.length === 0) throw new SyntaxError('Could not read hot looks');
+
+		return { url, entries };
+	}
+}
+
+export interface HabboHotLookList {
+	url: string;
+	entries: HabboHotLookListItem[];
+}
+
+export interface HabboHotLookListItem {
+	gender: 'f' | 'm';
+	figure: string;
+	hash: string;
+}

package/src/routes/marketplace.ts

@@ -0,0 +1,36 @@
+import { Json, type FetchResult } from '@skyra/safe-fetch';
+import { BaseAPI, type APIOptions } from './base.js';
+
+export class MarketplaceAPI extends BaseAPI {
+	/**
+	 * Get the marketplace stats for a room item
+	 *
+	 * @param roomItemName - The name of the room item
+	 * @param options - The options for the API call
+	 */
+	public getRoomItemStats(roomItemName: string, options?: APIOptions): Promise<FetchResult<MarketplaceStats>> {
+		const url = this.formatURL(`/api/public/marketplace/stats/roomItem/${roomItemName}`);
+		return Json<MarketplaceStats>(this.fetch(url, options));
+	}
+
+	/**
+	 * Get the marketplace stats for a wall item
+	 *
+	 * @param wallItemName - The name of the wall item
+	 * @param options - The options for the API call
+	 */
+	public getWallItemStats(wallItemName: string, options?: APIOptions): Promise<FetchResult<MarketplaceStats>> {
+		const url = this.formatURL(`/api/public/marketplace/stats/wallItem/${wallItemName}`);
+		return Json<MarketplaceStats>(this.fetch(url, options));
+	}
+}
+
+export interface MarketplaceStats {
+	status: 'OK';
+	statsDate: `${bigint}-${bigint}-${bigint}`;
+	soldItemCount: number;
+	creditSum: number;
+	averagePrice: number;
+	totalOpenOffers: number;
+	historyLimitInDays: number;
+}

package/src/routes/ping.ts

@@ -0,0 +1,17 @@
+import { type APIOptions, BaseAPI } from './base.js';
+
+export class PingAPI extends BaseAPI {
+	/**
+	 * Pings Habbo, returning the measured time using {@linkcode performance.now()}
+	 *
+	 * @param options - The options for the API call
+	 */
+	public async get(options?: APIOptions): Promise<number | null> {
+		const url = this.formatURL('/api/public/ping');
+		const now = performance.now();
+		return (await this.fetch(url, options)).match({
+			ok: () => performance.now() - now,
+			err: () => null
+		});
+	}
+}

package/src/routes/rooms.ts

@@ -0,0 +1,35 @@
+import { type FetchResult, Json } from '@skyra/safe-fetch';
+import { type APIOptions, BaseAPI } from './base.js';
+
+export class RoomsAPI extends BaseAPI {
+	/**
+	 * Get a room by its ID
+	 *
+	 * @param roomId - The ID of the room
+	 * @param options - The options for the API call
+	 */
+	public async getById(roomId: number, options?: APIOptions): Promise<FetchResult<HabboRoom>> {
+		const url = this.formatURL(`/api/public/rooms/${roomId}`);
+		return Json<HabboRoom>(this.fetch(url, options));
+	}
+}
+
+export interface HabboRoom {
+	id: number;
+	name: string;
+	description: string;
+	creationTime: `${bigint}-${bigint}-${bigint}T${string}`;
+	habboGroupId: string;
+	tags: string[];
+	maximumVisitors: number;
+	showOwnerName: boolean;
+	ownerName: string;
+	ownerUniqueId: string;
+	categories: string[];
+	thumbnailUrl: string;
+	imageUrl: string;
+	rating: number;
+	uniqueId: HabboRoomUniqueId;
+}
+
+export type HabboRoomUniqueId = `r-hh${string}-${string}`;