Alauda SDK

SDK oficial em JavaScript/TypeScript para a Alauda API - API Moçambicana para download de mídia social.

🚀 Características

• ✅ Suporte completo a TypeScript
• ✅ Autocomplete e intellisense
• ✅ Tratamento de erros integrado
• ✅ Suporte a Node.js e navegadores
• ✅ Documentação inline
• ✅ Promise-based (async/await)
• 🆕 Sistema de cache inteligente
• 🆕 Proteções automáticas para WhatsApp
• 🆕 Sistema de avisos progressivos

📦 Instalação

npm install alauda-sdk

🔑 Obter API Key

Crie sua conta gratuitamente em alauda-api.topaziocoin.online/dashboard e obtenha sua API Key.

📖 Uso Básico

const { AlaudaClient } = require('alauda-sdk');

const alauda = new AlaudaClient({
  apiKey: 'sua_api_key_aqui'
});

// Download de vídeo do TikTok
const video = await alauda.tiktok.download('https://www.tiktok.com/@user/video/123');
console.log(video.data.download.no_watermark);

📚 Exemplos

TikTok Download

const resultado = await alauda.tiktok.download('URL_DO_TIKTOK');

console.log('Título:', resultado.data.title);
console.log('Autor:', resultado.data.author.nickname);
console.log('Download HD:', resultado.data.download.no_watermark);
console.log('Créditos restantes:', resultado.credits_remaining);

Instagram Download

const resultado = await alauda.instagram.download('URL_DO_INSTAGRAM');

console.log('URL do arquivo:', resultado.data.download.no_watermark);
console.log('Créditos restantes:', resultado.credits_remaining);

YouTube Download

const resultado = await alauda.youtube.download('URL_DO_YOUTUBE');

console.log('Título:', resultado.data.title);
console.log('Download HD:', resultado.data.download.video_hd);
console.log('Áudio:', resultado.data.download.audio);

Spotify Download

const resultado = await alauda.spotify.download('URL_DO_SPOTIFY');

console.log('Música:', resultado.data.title);
console.log('Artista:', resultado.data.artist);
console.log('Download:', resultado.data.download);

Buscar Letra de Música

const resultado = await alauda.lyrics('Imagine Dragons', 'Believer');

console.log('Letra:', resultado.data.lyrics);
console.log('Metadata:', resultado.data.metadata);

Shazam (Identificar Música)

// A partir de um arquivo local
const resultado = await alauda.shazam('./audio.mp3');

// A partir de um Buffer
const fs = require('fs');
const buffer = fs.readFileSync('./audio.mp3');
const resultado = await alauda.shazam(buffer);

console.log('Música:', resultado.data.track.title);
console.log('Artista:', resultado.data.track.artist);

🛡️ WhatsApp Anti-Mention (NOVO v1.2.0)

Proteção automática e inteligente contra usuários que marcam o grupo no status do WhatsApp.

✨ Novidades da v1.2.0

• 🆕 Sistema de avisos progressivos - Dê chances antes de remover
• 🆕 Cache inteligente - Validações em cache para performance
• 🆕 Proteções automáticas - Admin, dono do bot e bot protegidos
• 🆕 Retry automático - Tenta remover 3x antes de falhar
• 🆕 Mensagens personalizáveis - Configure suas próprias mensagens
• 🆕 Retorno estruturado - Saiba exatamente o que aconteceu

🚀 Uso Básico

const { makeWASocket } = require('@whiskeysockets/baileys');
const { AlaudaClient } = require('alauda-sdk');

const sock = makeWASocket({ /* ... */ });

const alauda = new AlaudaClient({
  apiKey: 'alauda_live_sua_key'
});

// 1. Ativar o grupo
const ativacao = await alauda.whatsapp.activate(
  '[email protected]',
  'Nome do Grupo',
  '258123456789'
);

console.log(ativacao);
// {
//   success: true,
//   message: '✅ Grupo ativado com sucesso!',
//   credits_available: 1000,
//   cost_per_operation: 50
// }

// 2. Usar no bot (automático)
sock.ev.on('messages.upsert', async ({ messages }) => {
  for (const msg of messages) {
    const from = msg.key.remoteJid;
    
    // Proteção automática - só isso!
    await alauda.whatsapp.antiMention(msg, from, sock);
  }
});

🎯 Uso Avançado com Opções

const resultado = await alauda.whatsapp.antiMention(msg, groupId, sock, {
  maxWarnings: 3, // Quantos avisos antes de remover (padrão: 2)
  
  warningMessage: `⚠️ @{user}, não marque o grupo no status!\n\n` +
                  `📊 Avisos: {warnings}/{maxWarnings}\n` +
                  `🚫 Próxima vez será removido!`,
  
  removalMessage: `❌ @{user} foi removido!\n\n` +
                  `🛡️ Proteção Alauda ativa\n` +
                  `💰 Créditos: {credits}`
});

console.log(resultado);
// {
//   detected: true,
//   action: 'warned',           // ou 'removed', 'protected', 'no_credits'
//   warnings: 1,
//   max_warnings: 3,
//   credits_remaining: 950
// }

📋 Retornos Possíveis

// Não detectou mention
{ detected: false }

// Usuário recebeu aviso
{
  detected: true,
  action: 'warned',
  warnings: 1,
  max_warnings: 3,
  credits_remaining: 950
}

// Usuário foi removido
{
  detected: true,
  action: 'removed',
  warnings: 3,
  credits_remaining: 900
}

// Usuário está protegido (admin/dono)
{
  detected: true,
  action: 'protected',
  reason: 'group_admin' // ou 'bot_owner', 'bot'
}

// Sem créditos
{
  detected: true,
  action: 'no_credits'
}

// Grupo não autorizado
{
  detected: true,
  action: 'not_authorized',
  message: '❌ Grupo não ativado'
}

⚙️ Outros Métodos do WhatsApp

// Validar grupo (verifica créditos)
const validacao = await alauda.whatsapp.validate(groupId);
console.log(validacao);
// {
//   valid: true,
//   credits_available: 1000,
//   cost_per_operation: 50
// }

// Consumir créditos manualmente
const consumo = await alauda.whatsapp.consume(groupId);
console.log(consumo);
// {
//   success: true,
//   credits_consumed: 50,
//   credits_remaining: 950
// }

// Desativar grupo
await alauda.whatsapp.deactivate(groupId);

// Consultar status
const status = await alauda.whatsapp.status(groupId);
console.log(status);
// {
//   active: true,
//   group_name: 'Meu Grupo',
//   credits_available: 950,
//   operations_count: 1,
//   last_operation: '2024-01-15T10:30:00Z'
// }

🔧 Funcionalidades Incluídas

• ✅ Detecção automática de status mentions
• ✅ Sistema de avisos progressivos (configurável)
• ✅ Proteção automática para admins e dono do bot
• ✅ Cache inteligente de validações (5 minutos)
• ✅ Retry automático em caso de falha na remoção
• ✅ Mensagens personalizáveis via opções
• ✅ Logs detalhados no console
• ✅ Tratamento de erros robusto

💰 Custos WhatsApp

| Operação | Créditos | |----------|----------| | Ativar grupo | Grátis | | Validar grupo | Grátis | | Cada aviso dado | 50 | | Cada remoção | 50 | | Consultar status | Grátis |

🛠️ API Reference

AlaudaClient

new AlaudaClient(config: AlaudaConfig)

Parâmetros:

• apiKey (string, obrigatório): Sua API key da Alauda
• baseURL (string, opcional): URL base da API (default: https://alauda-api.topazioverse.com.br)

Endpoints Disponíveis

TikTok

• tiktok.download(url: string) - Baixa vídeo do TikTok
• tiktok.infoOnly(url: string) - Obtém apenas informações (consome menos créditos)

Instagram

• instagram.download(url: string) - Baixa posts do Instagram
• instagram.infoOnly(url: string) - Obtém apenas informações

YouTube

• youtube.download(url: string) - Baixa vídeos do YouTube
• youtube.infoOnly(url: string) - Obtém apenas informações

Spotify

• spotify.download(url: string) - Baixa músicas do Spotify

Lyrics

• lyrics(artist: string, title: string) - Busca letra de música

Shazam

• shazam(source: string | File | Buffer) - Identifica música de arquivo de áudio

Facebook

• facebook(url: string) - Baixa vídeos do Facebook

WhatsApp (v1.2.0)

• whatsapp.activate(groupId, groupName?, botNumber?) - Ativa proteção no grupo
• whatsapp.antiMention(msg, groupId, sock, options?) - Proteção automática
• whatsapp.validate(groupId) - Valida créditos do grupo
• whatsapp.consume(groupId) - Consome créditos
• whatsapp.deactivate(groupId) - Desativa grupo
• whatsapp.status(groupId) - Consulta status e uso

💰 Sistema de Créditos

Cada requisição consome créditos da sua conta:

| Endpoint | Créditos | |----------|----------| | TikTok Download | 100 | | Instagram Download | 100 | | YouTube Download | 200 | | Spotify Download | 100 | | Lyrics | 50 | | Shazam | 150 | | Facebook | 100 | | WhatsApp Anti-Mention | 50 |

10.000 requests = 100 MT (R$ 10)

🔒 Tratamento de Erros

O SDK lança erros descritivos para facilitar o debug:

try {
  const resultado = await alauda.tiktok.download('URL_INVALIDA');
} catch (error) {
  console.error('Erro:', error.message);
  // Possíveis erros:
  // - "API Key inválida ou ausente"
  // - "Créditos insuficientes"
  // - "Endpoint não encontrado"
  // - "Rate limit excedido"
}

📝 TypeScript

O SDK possui suporte completo a TypeScript com tipos incluídos:

import { 
  AlaudaClient, 
  VideoResponse,
  AntiMentionOptions,
  AntiMentionResult 
} from 'alauda-sdk';

const alauda = new AlaudaClient({ apiKey: 'sua_key' });

const video: VideoResponse = await alauda.tiktok.download('URL');

// WhatsApp com tipagem completa
const options: AntiMentionOptions = {
  maxWarnings: 3,
  warningMessage: 'Customizado'
};

const result: AntiMentionResult = await alauda.whatsapp.antiMention(
  msg, 
  groupId, 
  sock, 
  options
);

📦 Changelog

v1.2.0 (Atual)

• 🆕 Sistema de avisos progressivos no Anti-Mention
• 🆕 Cache inteligente de validações
• 🆕 Proteções automáticas (admin, dono, bot)
• 🆕 Retry automático na remoção
• 🆕 Mensagens personalizáveis
• 🆕 Retorno estruturado com detalhes
• 🆕 Novos métodos: validate(), consume(), status()
• ⚡ Performance melhorada com cache
• 🐛 Correções de tipagem TypeScript

v1.1.0

• WhatsApp Anti-Mention básico
• Endpoints principais (TikTok, Instagram, YouTube, Spotify)

🤝 Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para abrir issues ou pull requests.

1. Fork o projeto
2. Crie sua feature branch (git checkout -b feature/NovaFeature)
3. Commit suas mudanças (git commit -m 'Add: nova feature')
4. Push para a branch (git push origin feature/NovaFeature)
5. Abra um Pull Request

📄 Licença

MIT © Habibo Salimo Julio

🔗 Links

• Website da API
• Documentação Completa
• GitHub
• NPM

💬 Suporte

• WhatsApp: +258 86 284 0075
• Email: [email protected]

Desenvolvido com ❤️ por Habibo Salimo Julio em Moçambique 🇲🇿