Habbo API Wrapper para Go

Cliente Go idiomático para a API Web pública do Habbo Hotel. O núcleo HTTP usa apenas a biblioteca padrão; a ferramenta TUI opcional usa Bubble Tea. O domínio do hotel é informado pelo utilizador ou selecionado através das constantes oficiais (como habbo.HotelBR, habbo.HotelCOM), portanto o mesmo pacote funciona com https://www.habbo.com.br/, https://www.habbo.com/ e outros hotéis.

O cliente cobre todas as operações presentes na OpenAPI pública, incluindo Conquistas, Emblemas, Partidas, Grupos, Mercado, Pesca, Quartos, Habilidades, Usuários e Variáveis Wired.

Instalação

go get github.com/alynva/Habbo-API-Wrapper-Go

O módulo requer Go 1.24 ou superior.

Uso básico

package main

import (
	"context"
	"fmt"
	"log"
	"net/http"
	"time"

	habbo "github.com/alynva/Habbo-API-Wrapper-Go"
)

func main() {
	client, err := habbo.NewClient(
		habbo.HotelBR,
		habbo.WithHTTPClient(&http.Client{Timeout: 10 * time.Second}),
	)
	if err != nil {
		log.Fatal(err)
	}

	user, response, err := client.Users.ByName(context.Background(), "alynva", nil)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("%s (%s), HTTP %d\n", user.Name, user.UniqueID, response.StatusCode)
}

O Client é seguro para uso concorrente depois de construído. Cada método recebe um context.Context e devolve também um *habbo.Response, que preserva o status e os cabeçalhos HTTP (ETag, rate limit etc.). Pode-se injetar qualquer *http.Client, inclusive um cliente com transporte, proxy ou timeout próprios. O cabeçalho User-Agent enviado por padrão é HabboApiWrapperGo/1.0.

Wired Variables & Sanitização de Mobis

O quarto e as chaves são configurados uma única vez. O construtor exige um ID de quarto positivo e pelo menos uma chave:

client, err := habbo.NewWiredClient(
	habbo.HotelBR,
	123456,
	habbo.WiredKeys{
		ReadKey:  os.Getenv("HABBO_WIRED_READ_KEY"),
		WriteKey: os.Getenv("HABBO_WIRED_WRITE_KEY"),
	},
)

Também é possível habilitar Wired em um cliente comum:

client, err := habbo.NewClient(
	habbo.HotelBR,
	habbo.WithWired(123456, habbo.WiredKeys{ReadKey: readKey}),
)

Cada operação valida a credencial antes de fazer uma chamada HTTP:

• leituras exigem ReadKey;
• escritas exigem WriteKey;
• Batch exige ambas.

Os IDs de Mobis são automaticamente sanitizados através de SanitiseFurniID (convertendo IDs negativos e ajustando offsets do Builder's Club).

Leitura e escrita de um valor:

value, _, err := client.Wired.GetValue(
	ctx,
	habbo.WiredScopeUser,
	"score",
	habbo.WiredTargetUsers,
	"44",
)

updated, _, err := client.Wired.PutValue(
	ctx,
	habbo.WiredScopeUser,
	"score",
	habbo.WiredTargetUsers,
	"44",
	7,
)

Batch (de 1 a 50 operações):

results, _, err := client.Wired.Batch(
	ctx,
	habbo.WiredScopeUser,
	"score",
	[]habbo.WiredBatchOperation{
		{OperationID: "read", Method: habbo.WiredBatchGET, Path: "users/44"},
		{
			OperationID: "update",
			Method:      habbo.WiredBatchPATCH,
			Path:        "users/44",
			Body:        &habbo.WiredBatchOperationBody{Value: 7},
		},
	},
)

Para patches de perfil, nil remove uma variável user/furni:

score := int64(7)
profile, _, err := client.Wired.PatchUserProfile(
	ctx,
	habbo.WiredTargetUsers,
	"44",
	map[string]*int64{
		"score":  &score,
		"legacy": nil,
	},
)

Os enums de escopo e target são validados localmente. Por exemplo, WiredTargetUsers não pode ser usado com WiredScopeFurni.

Serviços disponíveis

Serviço	Operações principais
Achievements	catálogo e conquistas de um utilizador (UserAchievement)
Badges	contagem e detalhes dos donos de um emblema
Matches	IDs por player e detalhes de partidas Origins
Groups	detalhes e membros (com cores PrimaryColour e SecondaryColour)
Marketplace	estatísticas em batch de mobis e itens de parede
Derby	IDs, detalhes e status do Fishing Derby
Rooms	detalhes de quarto (PublicRoom e DoorMode)
Skills	skill e leaderboard
Lists	trajes em destaque (HotLooksResult decodificado de XML)
Users	lookup, perfil, amigos, grupos, quartos e emblemas com SelectedBadge
Wired	valores, listagem, count, bulk delete, batch, sanitização de mobis e perfis

Coleção Bruno API

O repositório inclui uma coleção nativa pronta no diretório bruno/ para uso no aplicativo Bruno.

Erros

Respostas fora da faixa 2xx produzem *habbo.ErrorResponse. O erro preserva a resposta HTTP, a mensagem/código reconhecido e até 1 MiB do corpo:

var apiErr *habbo.ErrorResponse
if errors.As(err, &apiErr) {
	fmt.Println(apiErr.Response.StatusCode, apiErr.Message)
}

Erros locais Wired podem ser verificados com errors.Is:

errors.Is(err, habbo.ErrWiredReadKeyRequired)
errors.Is(err, habbo.ErrWiredWriteKeyRequired)
errors.Is(err, habbo.ErrWiredNotConfigured)

Desenvolvimento

go generate ./...
go test ./...
go test -tags=publicintegration -run '^TestPublicEndpointsLive$' -v ./tests
go vet ./...

Os testes de contrato usam httptest. A suíte publicintegration, também executada pelo CI, consulta somente endpoints públicos de https://www.habbo.com.br/ com o usuário alynva e o ID hhbr-2b7ba818b78ef6254e7cf5dcd5ed9701; ela não usa chaves.

Os testes automáticos Wired também usam httptest: validam método, rota, payload e cabeçalhos contra um servidor local, sem qualquer chave real. O teste contra um quarto verdadeiro possui o build tag integration, não é selecionado pelo CI e deve ser iniciado pelo TUI:

go run ./cmd/wiredtest

O TUI solicita hostname, ID do quarto e as chaves, mascara os segredos e os mantém apenas na memória/processo filho. A suíte real é não destrutiva: executa leituras e, quando ambas as chaves estão disponíveis, um batch contendo somente GET.

Organização

src/             implementação do wrapper
tests/           contratos HTTP e suítes de integração
bruno/           coleção Bruno API nativa
cmd/gendocs/     gerador da referência da biblioteca
cmd/wiredtest/   TUI para iniciar o teste Wired real com segurança
docs/            referência HTML gerada para o GitHub Pages
.github/         CI sem segredos e publicação da documentação

A raiz contém uma fachada de aliases para preservar o import convencional github.com/alynva/Habbo-API-Wrapper-Go; consumidores não precisam importar /src.