@ejercito-fam/habbo-api 1.0.2 → 1.2.0

package/dist/esm/index.d.ts

@@ -0,0 +1,810 @@
+import { FetchResult } from '@skyra/safe-fetch';
+
+declare enum HotelDomainTLD {
+    Brazilian = ".com.br",
+    Danish = ".dk",
+    Dutch = ".nl",
+    Finnish = ".fi",
+    French = ".fr",
+    German = ".de",
+    International = ".com",
+    Italian = ".it",
+    Spanish = ".es",
+    Turkish = ".com.tr"
+}
+declare const HotelDomainURL: {
+    readonly Brazilian: "https://www.habbo.com.br";
+    readonly Danish: "https://www.habbo.dk";
+    readonly Dutch: "https://www.habbo.nl";
+    readonly Finnish: "https://www.habbo.fi";
+    readonly French: "https://www.habbo.fr";
+    readonly German: "https://www.habbo.de";
+    readonly International: "https://www.habbo.com";
+    readonly Italian: "https://www.habbo.it";
+    readonly Spanish: "https://www.habbo.es";
+    readonly Turkish: "https://www.habbo.com.tr";
+};
+
+declare abstract class BaseAPI {
+    #private;
+    protected readonly baseURL: string;
+    protected readonly timeout: number | null;
+    constructor(baseURL: string, timeout?: number | null | undefined);
+    protected formatURL(route: string): URL;
+    protected fetch(url: string | URL, options?: APIOptions): Promise<FetchResult<Response>>;
+}
+interface APIOptions {
+    signal?: AbortSignal | number | null | undefined;
+}
+
+declare 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
+     */
+    getByUniqueId(id: HabboGroupId, options?: APIOptions): Promise<FetchResult<HabboGroup>>;
+    /**
+     * Get the members from a group given its identifier
+     *
+     * @param id - The ID of the group
+     * @param options - The options for the API call
+     */
+    getGroupMembers(id: HabboGroupId, options?: APIOptions): Promise<FetchResult<HabboGroupMember[]>>;
+    /**
+     * 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
+     */
+    getGroupBadgeImageURL(badgeCode: string): URL;
+}
+type HabboGroupId = `g-hh${string}-${string};`;
+/**
+ * Represents a Habbo group.
+ */
+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.
+ */
+declare 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.
+ */
+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;
+}
+
+declare class UsersAPI extends BaseAPI {
+    /**
+     * Get a user by its username
+     *
+     * @param username - The username to search a Habbo user by
+     * @param options - The options for the API call
+     */
+    getByUsername(username: string, options?: APIOptions): Promise<FetchResult<HabboUser>>;
+    /**
+     * Get a user by its ID
+     *
+     * @param uniqueId - The ID to search a Habbo user by
+     * @param options - The options for the API call
+     */
+    getByUniqueId(uniqueId: string, options?: APIOptions): Promise<FetchResult<HabboUser>>;
+    /**
+     * Get a user's friends
+     *
+     * @param uniqueId - The ID to search a Habbo user by
+     * @param options - The options for the API call
+     */
+    getUserFriends(uniqueId: string, options?: APIOptions): Promise<FetchResult<HabboUserFriend[]>>;
+    /**
+     * Get a user's groups
+     *
+     * @param uniqueId - The ID to search a Habbo user by
+     * @param options - The options for the API call
+     */
+    getUserGroups(uniqueId: string, options?: APIOptions): Promise<FetchResult<HabboUserGroup[]>>;
+    /**
+     * Get a user's rooms
+     *
+     * @param uniqueId - The ID to search a Habbo user by
+     * @param options - The options for the API call
+     */
+    getUserRooms(uniqueId: string, options?: APIOptions): Promise<FetchResult<HabboUserRoom[]>>;
+    /**
+     * Get a user's badges
+     *
+     * @param uniqueId - The ID to search a Habbo user by
+     * @param options - The options for the API call
+     */
+    getUserBadges(uniqueId: string, options?: APIOptions): Promise<FetchResult<HabboUserBadge[]>>;
+    /**
+     * Get a user's profile
+     *
+     * @param uniqueId - The ID to search a Habbo user by
+     * @param options - The options for the API call
+     */
+    getUserProfile(uniqueId: string, options?: APIOptions): Promise<FetchResult<HabboUserProfile>>;
+    /**
+     * Get a user's photos
+     *
+     * @param uniqueId - The ID to search a Habbo user by
+     * @param options - The options for the API call
+     */
+    getUserPhotos(uniqueId: string, options?: APIOptions): Promise<FetchResult<HabboUserPhotos[]>>;
+    /**
+     * Get a user's figure
+     *
+     * @param options - The options for the image
+     */
+    getUserFigureImageURL(options: HabboFigureName | HabboFigureStatic): URL;
+}
+type HabboUserId = `hh${string}-${string}`;
+/**
+ * Represents a Habbo user.
+ */
+interface HabboUser {
+    /**
+     * The unique identifier of the user.
+     */
+    uniqueId: HabboUserId;
+    /**
+     * The name of the user.
+     */
+    name: string;
+    /**
+     * The figure string of the user.
+     */
+    figureString: string;
+    /**
+     * The motto of the user.
+     */
+    motto: string;
+    /**
+     * Indicates whether the user is online.
+     */
+    online: boolean;
+    /**
+     * The last access time of the user.
+     */
+    lastAccessTime: string;
+    /**
+     * The date when the user became a member.
+     */
+    memberSince: string;
+    /**
+     * Indicates whether the user's profile is visible.
+     */
+    profileVisible: boolean;
+    /**
+     * The current level of the user.
+     */
+    currentLevel: number;
+    /**
+     * The percentage of the current level completed by the user.
+     */
+    currentLevelCompletePercent: number;
+    /**
+     * The total experience points of the user.
+     */
+    totalExperience: number;
+    /**
+     * The number of star gems the user has.
+     */
+    starGemCount: number;
+    /**
+     * The badges selected by the user.
+     */
+    selectedBadges: HabboUserSelectedBadge[];
+}
+/**
+ * Represents a room owned by a Habbo user.
+ */
+interface HabboUserRoom {
+    /**
+     * The unique identifier of the room.
+     */
+    id: number;
+    /**
+     * The name of the room.
+     */
+    name: string;
+    /**
+     * The description of the room.
+     */
+    description: string;
+    /**
+     * The creation time of the room.
+     */
+    creationTime: string;
+    /**
+     * The unique identifier of the Habbo group associated with the room.
+     */
+    habboGroupId: string;
+    /**
+     * The tags associated with the room.
+     */
+    tags: string[];
+    /**
+     * The maximum number of visitors allowed in the room.
+     */
+    maximumVisitors: number;
+    /**
+     * Indicates whether the owner's name is shown.
+     */
+    showOwnerName: boolean;
+    /**
+     * The name of the room owner.
+     */
+    ownerName: string;
+    /**
+     * The unique identifier of the room owner.
+     */
+    ownerUniqueId: string;
+    /**
+     * The categories associated with the room.
+     */
+    categories: string[];
+    /**
+     * The URL of the room's thumbnail image.
+     */
+    thumbnailUrl: string;
+    /**
+     * The URL of the room's image.
+     */
+    imageUrl: string;
+    /**
+     * The rating of the room.
+     */
+    rating: number;
+    /**
+     * The unique identifier of the room.
+     */
+    uniqueId: string;
+}
+/**
+ * Represents a group associated with a Habbo user.
+ */
+interface HabboUserGroup {
+    /**
+     * Indicates whether the group is online.
+     */
+    online: boolean;
+    /**
+     * The unique identifier of the group.
+     */
+    id: string;
+    /**
+     * The name of the group.
+     */
+    name: string;
+    /**
+     * The description of the group.
+     */
+    description: string;
+    /**
+     * The type of the group.
+     */
+    type: HabboGroupType;
+    /**
+     * The unique identifier of the room associated with the group.
+     */
+    roomId: string;
+    /**
+     * The badge code of the group.
+     */
+    badgeCode: string;
+    /**
+     * The primary color of the group.
+     */
+    primaryColour: string;
+    /**
+     * The secondary color of the group.
+     */
+    secondaryColour: string;
+    /**
+     * Indicates whether the user is an admin of the group.
+     */
+    isAdmin: boolean;
+}
+/**
+ * Represents a badge owned by a Habbo user.
+ */
+interface HabboUserBadge {
+    /**
+     * The code of the badge.
+     */
+    code: string;
+    /**
+     * The name of the badge.
+     */
+    name: string;
+    /**
+     * The description of the badge.
+     */
+    description: string;
+}
+/**
+ * Represents a selected badge of a Habbo user.
+ */
+interface HabboUserSelectedBadge extends HabboUserBadge {
+    /**
+     * The index of the badge.
+     */
+    badgeIndex: number;
+}
+/**
+ * Represents a friend of a Habbo user.
+ */
+interface HabboUserFriend {
+    /**
+     * The unique identifier of the friend.
+     */
+    uniqueId: string;
+    /**
+     * The name of the friend.
+     */
+    name: string;
+    /**
+     * The figure string of the friend.
+     */
+    figureString: string;
+    /**
+     * The motto of the friend.
+     */
+    motto: string;
+    /**
+     * Indicates whether the friend is online.
+     */
+    online: boolean;
+}
+/**
+ * Represents the profile of a Habbo user.
+ */
+interface HabboUserProfile {
+    /**
+     * The unique identifier of the user.
+     */
+    uniqueId: string;
+    /**
+     * The name of the user.
+     */
+    name: string;
+    /**
+     * The figure string of the user.
+     */
+    figureString: string;
+    /**
+     * The motto of the user.
+     */
+    motto: string;
+    /**
+     * Indicates whether the user is online.
+     */
+    online: boolean;
+    /**
+     * The last access time of the user.
+     */
+    lastAccessTime: string;
+    /**
+     * The date when the user became a member.
+     */
+    memberSince: string;
+    /**
+     * Indicates whether the user's profile is visible.
+     */
+    profileVisible: boolean;
+    /**
+     * The current level of the user.
+     */
+    currentLevel: number;
+    /**
+     * The percentage of the current level completed by the user.
+     */
+    currentLevelCompletePercent: number;
+    /**
+     * The total experience points of the user.
+     */
+    totalExperience: number;
+    /**
+     * The number of star gems the user has.
+     */
+    starGemCount: number;
+    /**
+     * The badges selected by the user.
+     */
+    selectedBadges: HabboUserSelectedBadge[];
+    /**
+     * The groups the user is a member of.
+     */
+    groups: HabboUserGroup[];
+    /**
+     * The badges owned by the user.
+     */
+    badges: HabboUserBadge[];
+    /**
+     * The friends of the user.
+     */
+    friends: HabboUserFriend[];
+    /**
+     * The rooms owned by the user.
+     */
+    rooms: HabboUserRoom[];
+}
+/**
+ * Represents photos associated with a Habbo user.
+ */
+interface HabboUserPhotos {
+    /**
+     * The unique identifier of the room where the photo was taken.
+     */
+    room_id: number;
+    /**
+     * The unique identifier of the photo creator.
+     */
+    creator_id: number;
+    /**
+     * The name of the photo creator.
+     */
+    creator_name: string;
+    /**
+     * The time when the photo was taken.
+     */
+    time: number;
+    /**
+     * The version of the photo.
+     */
+    version: number;
+    /**
+     * The URL of the photo.
+     */
+    url: string;
+    /**
+     * The type of the photo.
+     */
+    type: string;
+    /**
+     * The unique identifier of the photo creator.
+     */
+    creator_uniqueId: string;
+    /**
+     * The tags associated with the photo.
+     */
+    tags: string[];
+    /**
+     * The URL of the photo preview.
+     */
+    previewUrl: string;
+    /**
+     * The unique identifier of the photo.
+     */
+    id: string;
+    /**
+     * The likes associated with the photo.
+     */
+    likes: string[];
+}
+interface HabboFigureName extends HabboFigureBase {
+    /**
+     * The Habbo username.
+     */
+    user: string;
+}
+interface HabboFigureStatic extends HabboFigureBase {
+    /**
+     * The Habbo figure to use.
+     */
+    figure: string;
+    /**
+     * The Habbo's gender.
+     */
+    gender?: keyof typeof HabboFigureGender | undefined | null;
+}
+interface HabboFigureBase {
+    /**
+     * The action the user should perform.
+     */
+    action?: keyof typeof HabboFigureAction | undefined | null;
+    /**
+     * The hand item, will override {@linkcode HabboFigureBase.action} to `'crr'`.
+     */
+    hand?: keyof typeof HabboFigureHand | undefined | null;
+    /**
+     * The Habbo's direction.
+     */
+    direction?: keyof typeof HabboFigureDirection | undefined | null;
+    /**
+     * The Habbo's head direction.
+     */
+    headDirection?: keyof typeof HabboFigureDirection | undefined | null;
+    /**
+     * The gesture, if any.
+     */
+    gesture?: keyof typeof HabboFigureGesture | undefined | null;
+    /**
+     * The size of the character.
+     */
+    size?: keyof typeof HabboFigureSize | undefined | null;
+    /**
+     * Whether or not to render only the head.
+     */
+    headOnly?: boolean | undefined | null;
+}
+declare const HabboFigureAction: {
+    readonly lay: "lay";
+    readonly sit: "sit";
+    readonly respect: "respect";
+    readonly walk: "wlk";
+    readonly wave: "wav";
+    readonly carry: "crr";
+    readonly drink: "drk";
+    readonly sign: "sig";
+    readonly blow: "blw";
+    readonly laugh: "laugh";
+};
+declare const HabboFigureHand: {
+    readonly nothing: "0";
+    readonly carrot: "2";
+    readonly coffee: "6";
+    readonly cocktail: "667";
+    readonly habbo_cola: "5";
+    readonly ice_cream: "3";
+    readonly japanese_tea: "42";
+    readonly love_potion: "9";
+    readonly radioactive: "44";
+    readonly tomato: "43";
+    readonly water: "1";
+};
+declare const HabboFigureGesture: {
+    readonly nothing: "nrm";
+    readonly happy: "sml";
+    readonly sad: "sad";
+    readonly angry: "agr";
+    readonly surprised: "srp";
+    readonly sleeping: "eyb";
+    readonly speaking: "spk";
+};
+declare const HabboFigureSize: {
+    readonly small: "s";
+    readonly normal: "m";
+    readonly large: "l";
+};
+declare const HabboFigureDirection: {
+    readonly nw: "0";
+    readonly w: "1";
+    readonly sw: "2";
+    readonly s: "3";
+    readonly se: "4";
+    readonly e: "5";
+    readonly ne: "6";
+    readonly n: "7";
+};
+declare const HabboFigureGender: {
+    readonly male: "M";
+    readonly female: "F";
+};
+declare const HabboFigureGestureKeys: (keyof typeof HabboFigureGesture)[];
+declare const HabboFigureActionKeys: (keyof typeof HabboFigureAction)[];
+declare const HabboFigureHandKeys: (keyof typeof HabboFigureHand)[];
+declare const HabboFigureSizeKeys: (keyof typeof HabboFigureSize)[];
+declare const HabboFigureDirectionKeys: (keyof typeof HabboFigureDirection)[];
+declare const HabboFigureGenderKeys: (keyof typeof HabboFigureGender)[];
+
+declare class AchievementsAPI extends BaseAPI {
+    /**
+     * Get all achievements
+     *
+     * @param options - The options for the API call
+     */
+    getAll(options?: APIOptions): Promise<FetchResult<Achievement[]>>;
+    /**
+     * Get the achievements from a specified user ID
+     *
+     * @param id - The ID of the user
+     * @param options - The options for the API call
+     */
+    getByUserId(id: HabboUserId, options?: APIOptions): Promise<FetchResult<UserAchievement[]>>;
+    /**
+     * 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
+     */
+    getImageURL(achievementName: string): URL;
+}
+interface Achievement {
+    achievement: AchievementData;
+    levelRequirements: AchievementRequirements;
+}
+interface UserAchievement {
+    achievement: AchievementData;
+    level: number;
+    score: number;
+}
+interface AchievementData {
+    id: number;
+    name: string;
+    creationTime: `${bigint}-${bigint}-${bigint}`;
+    state: AchievementDataState;
+    category: string;
+}
+declare enum AchievementDataState {
+    Enabled = "ENABLED",
+    Archived = "ARCHIVED",
+    OffSeason = "OFF_SEASON"
+}
+interface AchievementRequirements {
+    level: number;
+    requiredScore: number;
+}
+
+declare class ListsAPI extends BaseAPI {
+    #private;
+    /**
+     * Get the hot looks from the hotel
+     *
+     * @param options - The options for the API call
+     */
+    getHotLooks(options: APIOptions): Promise<FetchResult<HabboHotLookList>>;
+}
+interface HabboHotLookList {
+    url: string;
+    entries: HabboHotLookListItem[];
+}
+interface HabboHotLookListItem {
+    gender: 'f' | 'm';
+    figure: string;
+    hash: string;
+}
+
+declare 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
+     */
+    getRoomItemStats(roomItemName: string, options?: APIOptions): Promise<FetchResult<MarketplaceStats>>;
+    /**
+     * Get the marketplace stats for a wall item
+     *
+     * @param wallItemName - The name of the wall item
+     * @param options - The options for the API call
+     */
+    getWallItemStats(wallItemName: string, options?: APIOptions): Promise<FetchResult<MarketplaceStats>>;
+}
+interface MarketplaceStats {
+    status: 'OK';
+    statsDate: `${bigint}-${bigint}-${bigint}`;
+    soldItemCount: number;
+    creditSum: number;
+    averagePrice: number;
+    totalOpenOffers: number;
+    historyLimitInDays: number;
+}
+
+declare class PingAPI extends BaseAPI {
+    /**
+     * Pings Habbo, returning the measured time using {@linkcode performance.now()}
+     *
+     * @param options - The options for the API call
+     */
+    get(options?: APIOptions): Promise<number | null>;
+}
+
+declare 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
+     */
+    getById(roomId: number, options?: APIOptions): Promise<FetchResult<HabboRoom>>;
+}
+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;
+}
+type HabboRoomUniqueId = `r-hh${string}-${string}`;
+
+declare class Habbo {
+    readonly achievements: AchievementsAPI;
+    readonly groups: GroupsAPI;
+    readonly lists: ListsAPI;
+    readonly marketplace: MarketplaceAPI;
+    readonly ping: PingAPI;
+    readonly rooms: RoomsAPI;
+    readonly users: UsersAPI;
+    constructor(options?: HabboOptions);
+}
+interface HabboOptions {
+    baseURL?: string | null | undefined;
+    timeout?: number | null | undefined;
+}
+
+export { type Achievement, type AchievementData, AchievementDataState, type AchievementRequirements, AchievementsAPI, GroupsAPI, Habbo, HabboFigureAction, HabboFigureActionKeys, type HabboFigureBase, HabboFigureDirection, HabboFigureDirectionKeys, HabboFigureGender, HabboFigureGenderKeys, HabboFigureGesture, HabboFigureGestureKeys, HabboFigureHand, HabboFigureHandKeys, type HabboFigureName, HabboFigureSize, HabboFigureSizeKeys, type HabboFigureStatic, type HabboGroup, type HabboGroupId, type HabboGroupMember, HabboGroupType, type HabboHotLookList, type HabboHotLookListItem, type HabboOptions, type HabboRoom, type HabboRoomUniqueId, type HabboUser, type HabboUserBadge, type HabboUserFriend, type HabboUserGroup, type HabboUserId, type HabboUserPhotos, type HabboUserProfile, type HabboUserRoom, type HabboUserSelectedBadge, HotelDomainTLD, HotelDomainURL, ListsAPI, MarketplaceAPI, type MarketplaceStats, PingAPI, RoomsAPI, type UserAchievement, UsersAPI };