Classe UnderDeck

Classe UnderDeck

A classe UnderDeck é o ponto central da biblioteca UnderDeckLib, atuando como o principal orquestrador para todas as interações com o ecossistema UnderDeck. Ela estende EventEmitter do Node.js, o que permite que a biblioteca emita eventos importantes durante seu ciclo de vida e operações, e que os desenvolvedores possam se inscrever nesses eventos para reagir a mudanças de estado ou resultados de operações de forma assíncrona.

Esta classe encapsula a lógica para a comunicação via WebSocket, a interação com a API REST, o gerenciamento de autenticação e dados do usuário, e a interface com dispositivos ESP32. Ao instanciar UnderDeck, você obtém acesso a um conjunto robusto de funcionalidades para integrar seu aplicativo com os serviços UnderDeck.

Instanciação

Para começar a usar a biblioteca, você precisa importar e instanciar a classe UnderDeck:

import UnderDeck from 'underdecklib';

const client = new UnderDeck();

Propriedades

A classe UnderDeck expõe várias propriedades que gerenciam o estado interno e fornecem acesso a outras funcionalidades da biblioteca.

Esp32MultiManager

• Tipo: Esp32MultiManager
• Descrição: Uma instância da classe Esp32MultiManager, responsável por descobrir, conectar e gerenciar a comunicação serial com múltiplos dispositivos ESP32. Através desta propriedade, você pode interagir diretamente com seus dispositivos embarcados.

Api

• Tipo: Api
• Descrição: Uma instância da classe Api, que abstrai todas as chamadas para a API REST do UnderDeck. Utilize esta propriedade para realizar requisições HTTP autenticadas e não autenticadas aos serviços de backend.

Socket

• Tipo: ReconnectingWebSocket
• Descrição: A instância do WebSocket que mantém uma conexão persistente e reconectável com o servidor UnderDeck. Esta propriedade é utilizada internamente para comunicação em tempo real e não deve ser manipulada diretamente, a menos que você tenha um caso de uso muito específico.

User

• Tipo: Models.User ou null
• Descrição: Um objeto que contém os dados do usuário atualmente autenticado. Este objeto é preenchido após um login ou autenticação bem-sucedida e é null caso não haja usuário logado. Ele inclui informações como ID, nome de usuário, email, status de premium, amigos, e estilo de perfil.

MyMac

• Tipo: string ou null
• Descrição: O endereço MAC da máquina onde a biblioteca está sendo executada. É obtido automaticamente durante a inicialização e usado para identificar o PC no ecossistema UnderDeck.

Pc

• Tipo: Models.PC ou null
• Descrição: Um objeto que representa o PC atual registrado no sistema UnderDeck. Contém informações como ID do PC, nome e endereço MAC. É preenchido após o registro bem-sucedido do PC.

Métodos

Os métodos da classe UnderDeck fornecem a interface programática para interagir com as diversas funcionalidades da biblioteca.

constructor()

new UnderDeck()

• Descrição: O construtor da classe UnderDeck. Ele inicializa a instância, configura os gerenciadores Esp32MultiManager e Api, e inicia o processo de obtenção do endereço MAC da máquina. Além disso, ele configura um ouvinte para o evento Ready, que é disparado após a autenticação do usuário e o registro do PC.

SocketConnect()

await client.SocketConnect()

• Descrição: Estabelece ou verifica a conexão com o servidor WebSocket. Este método é chamado internamente pela maioria dos outros métodos que dependem de comunicação em tempo real. Ele garante que uma conexão WebSocket esteja ativa e pronta para uso. Retorna uma Promise que resolve para true se a conexão for bem-sucedida ou já estiver aberta.
• Retorna: Promise<boolean>

GetMyMac()

await client.GetMyMac()

• Descrição: Retorna o endereço MAC da máquina local. Se o endereço MAC já foi obtido, ele retorna o valor em cache. Caso contrário, ele o obtém usando a biblioteca macaddress.
• Retorna: Promise<string> O endereço MAC da máquina.

LanguageId (setter)

client.LanguageId = 'pt_br';

• Descrição: Define o idioma preferencial para as mensagens de resposta da API e do WebSocket. Ao definir esta propriedade, o idioma é automaticamente propagado para a instância Api.
• Parâmetros:
  • value (string): O código do idioma (ex: 'en_us', 'pt_br').

EnableOthersConnectThisClient (setter)

client.EnableOthersConnectThisClient = true;

• Descrição: Controla se outros clientes têm permissão para se conectar a este PC. Definir como true permite que outros usuários interajam com este PC através da plataforma UnderDeck. O valor é convertido para um booleano estrito.
• Parâmetros:
  • value (boolean): true para habilitar, false para desabilitar.

RegisterThisPc()

await client.RegisterThisPc()

• Descrição: Registra o PC atual no sistema UnderDeck. Este método coleta informações do sistema operacional e o endereço MAC, e as envia para a API para registrar ou atualizar os dados do PC. É crucial para que o PC seja reconhecido e gerenciável na plataforma. Ele também envia uma mensagem

WebSocket indicando que o PC está pronto.

• Retorna: Promise<Models.PC|null|boolean> Um objeto PC se o registro for bem-sucedido, null se o usuário não estiver autenticado, ou false em caso de erro.

SendSocketMessage(Message, Method)

await client.SendSocketMessage({ Id: client.Pc.id }, 'Ready');

• Descrição: Envia uma mensagem ou objeto para o servidor WebSocket. Esta é a forma principal de comunicação em tempo real com o backend UnderDeck. As mensagens enviadas através deste método podem ser processadas pelo servidor e resultar em eventos ou respostas específicas.
• Parâmetros:
  • Message (object): O objeto de dados a ser enviado.
  • Method (string, opcional): O método associado à mensagem (padrão: null).
• Retorna: Promise<boolean> true se a mensagem foi enviada com sucesso, false caso contrário.

GetAccount()

const userAccount = await client.GetAccount();
if (userAccount) {
    console.log("Usuário logado:", userAccount.username);
}

• Descrição: Obtém os detalhes da conta do usuário atualmente autenticado. Este método é útil para atualizar as informações do objeto User local com os dados mais recentes do servidor.
• Retorna: Promise<Models.User|boolean|null> Um objeto User se a conta for obtida com sucesso, false se o usuário não estiver autenticado ou a API retornar false, ou null em caso de erro.

GetMyFriends()

const friends = await client.GetMyFriends();
friends.forEach(friend => console.log(friend.username));

• Descrição: Recupera a lista de amigos do usuário autenticado. A lista é retornada como um Map de objetos User.
• Retorna: Promise<Map<Models.User, Models.User>> Um Map contendo os amigos do usuário, ou um Map vazio se não houver amigos ou em caso de erro.

FindUserByName(Name)

const foundUsers = await client.FindUserByName("NomeDoUsuario");
foundUsers.forEach(user => console.log(user.username));

• Descrição: Permite buscar usuários na plataforma UnderDeck pelo nome. Este método é útil para funcionalidades como adicionar amigos ou procurar por outros usuários.
• Parâmetros:
  • Name (string): O nome do usuário a ser buscado.
• Retorna: Promise<Models.UsersList|null> Um objeto UsersList contendo os usuários encontrados, ou null em caso de erro.

UpdateUser(ObjectToUpdate)

await client.UpdateUser({ name: "Novo Nome", email: "[email protected]" });

• Descrição: Atualiza os dados do perfil do usuário autenticado. Você pode passar um objeto contendo as propriedades do usuário que deseja modificar. Após a atualização, o método GetAccount() é chamado para garantir que o objeto User local esteja sincronizado.
• Parâmetros:
  • ObjectToUpdate (object): Um objeto contendo as propriedades do usuário a serem atualizadas.
• Retorna: Promise<boolean> true se a atualização for bem-sucedida, false caso contrário.

GetThemes()

const themes = await client.GetThemes();
console.log("Temas de aplicativo:", themes.appThemes);

• Descrição: Obtém uma lista de temas disponíveis para o aplicativo e para o usuário (como NamePlates e Backgrounds). Isso permite a personalização da interface do usuário.
• Retorna: Promise<object> Um objeto contendo appThemes, userNamePlates e userBackgrounds, ou um array vazio em caso de erro.

GetPlugins()

const plugins = await client.GetPlugins();
plugins.forEach(plugin => console.log(plugin.name));

• Descrição: Recupera uma lista de plugins disponíveis para o aplicativo. Esta funcionalidade permite estender as capacidades da plataforma UnderDeck.
• Retorna: Promise<object[]> Um array de objetos de plugin, ou um array vazio em caso de erro.

DefineMyTheme(namePlateId, backgroundId)

await client.DefineMyTheme("someNamePlateId", "someBackgroundId");

• Descrição: Permite ao usuário definir seu tema de perfil, NamePlate e Background. Os IDs fornecidos devem corresponder aos temas disponíveis obtidos via GetThemes().
• Parâmetros:
  • namePlateId (string, opcional): O ID do NamePlate a ser definido.
  • backgroundId (string, opcional): O ID do Background a ser definido.
• Retorna: Promise<boolean|null> true se o tema for definido com sucesso, false se o usuário não estiver autenticado ou a API retornar false, ou null em caso de erro.

ChangeAvatar(file, Width, Height, Left, Top)

// Exemplo de uso (requer um objeto de arquivo)
// const avatarFile = new File([fileBuffer Ou fileBlob], fileName, { type: 'image/png' });
// Ou
// const avatarFile = {
//  type: 'file',
//  data: new Blob([fileBuffer Ou fileBlob]),
//  name: fileName
// };
// await client.ChangeAvatar(avatarFile, 100, 100, 0, 0);

• Descrição: Permite ao usuário alterar seu avatar. Este método aceita um objeto de arquivo e, opcionalmente, parâmetros para redimensionamento e corte da imagem.
• Parâmetros:
  • file (any): O arquivo do avatar a ser enviado (formato específico depende da implementação da API).
  • Width (number, opcional): Largura desejada para o avatar.
  • Height (number, opcional): Altura desejada para o avatar.
  • Left (number, opcional): Posição de corte à esquerda.
  • Top (number, opcional): Posição de corte superior.
• Retorna: Promise<boolean> true se o avatar for alterado com sucesso, false caso contrário.

SendFriendRequest(UserId)

await client.SendFriendRequest("someUserId");

• Descrição: Envia uma solicitação de amizade para outro usuário na plataforma.
• Parâmetros:
  • UserId (string): O ID do usuário para quem enviar a solicitação de amizade.
• Retorna: Promise<boolean> true se a solicitação for enviada com sucesso, false caso contrário.

RequestUnFriend(RequestId)

await client.RequestUnFriend("someRequestId");

• Descrição: Cancela uma solicitação de amizade pendente ou remove um amigo existente. O RequestId pode ser o ID da solicitação ou o ID do amigo.
• Parâmetros:
  • RequestId (string): O ID da solicitação de amizade ou do amigo a ser removido.
• Retorna: Promise<boolean> true se a ação for bem-sucedida, false caso contrário.

AcceptFriendRequest(RequestId)

await client.AcceptFriendRequest("someRequestId");

• Descrição: Aceita uma solicitação de amizade recebida. Isso adiciona o remetente da solicitação à lista de amigos do usuário.
• Parâmetros:
  • RequestId (string): O ID da solicitação de amizade a ser aceita.
• Retorna: Promise<boolean> true se a solicitação for aceita com sucesso, false caso contrário.

RejectFriendRequest(RequestId)

await client.RejectFriendRequest("someRequestId");

• Descrição: Rejeita uma solicitação de amizade recebida. Isso impede que o remetente da solicitação seja adicionado à lista de amigos.
• Parâmetros:
  • RequestId (string): O ID da solicitação de amizade a ser rejeitada.
• Retorna: Promise<boolean> true se a solicitação for rejeitada com sucesso, false caso contrário.

ResendFriendRequest(RequestId)

await client.ResendFriendRequest("someRequestId");

• Descrição: Reenvia uma solicitação de amizade que foi previamente enviada, mas talvez não tenha sido respondida ou tenha expirado.
• Parâmetros:
  • RequestId (string): O ID da solicitação de amizade a ser reenviada.
• Retorna: Promise<boolean> true se a solicitação for reenviada com sucesso, false caso contrário.

RevokeAllPermissionForPC()

await client.RevokeAllPermissionForPC();

• Descrição: Remove todas as permissões concedidas a outros usuários para se conectarem a este PC. Isso aumenta a segurança e o controle sobre quem pode interagir com sua máquina.
• Retorna: Promise<boolean|null> true se as permissões forem revogadas com sucesso, false se o usuário não estiver autenticado ou a API retornar false, ou null em caso de erro.

CloudUploadData(DataToUpload, callBack)

// Exemplo de DataToUpload:
// const data = {
//     Itens: [{ key: "config", value: { setting1: true } }],
//     FilesToUpload: [{ files: [{ dirFile: "/path/to/file.txt" }] }]
// };
// await client.CloudUploadData(data, (progress) => console.log(progress.percent + "% concluído"));

• Descrição: Faz upload de dados e arquivos para o serviço de armazenamento em nuvem do UnderDeck. Este método é assíncrono e pode incluir um callback para monitorar o progresso do upload.
• Parâmetros:
  • DataToUpload (object): Um objeto contendo os dados e arquivos a serem enviados. Deve incluir Itens (dados JSON) e FilesToUpload (array de objetos de arquivo).
  • callBack (function, opcional): Uma função de callback que recebe um objeto de progresso durante o upload.
• Retorna: Promise<object|boolean> Um objeto com os dados da resposta do upload se for bem-sucedido, false caso contrário.

GetSynchronizedData()

const cloudData = await client.GetSynchronizedData();
console.log("Dados da nuvem:", cloudData);

• Descrição: Recupera os dados do usuário que foram sincronizados e armazenados na nuvem. Isso permite que os usuários acessem seus dados de qualquer lugar.
• Retorna: Promise<object|boolean> Um objeto com os dados sincronizados se for bem-sucedido, false caso contrário.

ClearSynchronizedData()

await client.ClearSynchronizedData();

• Descrição: Limpa todos os dados do usuário armazenados na nuvem. Esta é uma operação sensível e deve ser usada com cautela.
• Retorna: Promise<object|boolean> Um objeto com a resposta da operação se for bem-sucedida, false caso contrário.

SendMsgConfirmEmail()

await client.SendMsgConfirmEmail();

• Descrição: Envia um e-mail de confirmação para o endereço de e-mail do usuário autenticado. Isso é comumente usado para verificar a propriedade do e-mail.
• Retorna: Promise<object|boolean> Um objeto com a resposta da operação se for bem-sucedida, false caso contrário.

RequestCodeChangePassword(Username)

await client.RequestCodeChangePassword("username_or_email");

• Descrição: Solicita um código para iniciar o processo de alteração de senha. O código é geralmente enviado para o e-mail associado ao nome de usuário ou e-mail fornecido.
• Parâmetros:
  • Username (string): O nome de usuário ou e-mail do qual se deseja alterar a senha.
• Retorna: Promise<object|boolean> Um objeto com a resposta da operação se for bem-sucedida, false caso contrário.

ChangePassword(ClientId, Code, Password, CPassword)

await client.ChangePassword("clientId", "verificationCode", "newPassword", "confirmNewPassword");

• Descrição: Altera a senha do usuário usando um código de verificação previamente solicitado. Requer o ID do cliente, o código de verificação, a nova senha e a confirmação da nova senha.
• Parâmetros:
  • ClientId (string): O ID do cliente recebido com a solicitação do código.
  • Code (string): O código de verificação para confirmar a alteração da senha.
  • Password (string): A nova senha.
  • CPassword (string): A confirmação da nova senha.
• Retorna: Promise<object|boolean> Um objeto com a resposta da operação se for bem-sucedida, false caso contrário.

UserRegister(UserData)

const newUser = await client.UserRegister({
    name: "João Silva",
    username: "joao.silva",
    email: "[email protected]",
    password: "senhaSegura123",
    cpassword: "senhaSegura123"
});

• Descrição: Registra um novo usuário na plataforma UnderDeck. Requer um objeto UserData contendo informações como nome, nome de usuário, e-mail, senha e confirmação de senha. Após o registro bem-sucedido, o usuário é automaticamente logado e o PC é registrado.
• Parâmetros:
  • UserData (object): Um objeto contendo os dados do novo usuário.
• Retorna: Promise<Models.User|null|boolean> Um objeto User se o registro for bem-sucedido, null se UserData não for um objeto, ou false em caso de erro.

Logout()

await client.Logout();

• Descrição: Realiza o logout do usuário da plataforma UnderDeck. Limpa as informações do usuário e do PC da instância e emite o evento Logout.
• Retorna: Promise<boolean> true se o logout for bem-sucedido, false caso contrário.

Login(Username, Password)

await client.Login("seu_usuario", "sua_senha");

• Descrição: Autentica o usuário na plataforma UnderDeck usando nome de usuário e senha. Em caso de sucesso, o objeto User é preenchido e o PC é registrado. Emite os eventos Ready ou UserFailed.
• Parâmetros:
  • Username (string): O nome de usuário ou e-mail.
  • Password (string): A senha do usuário.
• Retorna: Promise<Models.User|boolean|null> true se o login for bem-sucedido, false se as credenciais forem inválidas, ou null em caso de erro.

Auth(Token)

await client.Auth("seu_token_de_autenticacao");

• Descrição: Autentica o usuário na plataforma UnderDeck usando um token de autenticação. Fornecido após o Login. Emite os eventos Ready ou UserFailed.
• Parâmetros:
  • Token (string): O token de autenticação.
• Retorna: Promise<Models.User|boolean|null> true se a autenticação for bem-sucedida, false se o token for inválido, ou null em caso de erro.