Resetnak/domain-availability-skill

Verificando Disponibilidade de Domínio

Visão Geral

Verifica se um nome está disponível em três superfícies das quais uma decisão de nomeação de projeto geralmente depende: TLDs de domínio, nome de pacote npm e nome de usuário/org no GitHub. Cada verificação é uma chamada de API separada, gratuita e sem chave — execute-as juntas quando o usuário estiver nomeando algo, ou apenas a verificação de domínio quando isso for tudo o que ele pediu.

API de Domínio

GET https://domainee.dev/api/v1/tools/domain-availability-checker?name=<nome>&tlds=<tld>&tlds=<tld>...

• name (obrigatório) — nome de domínio sem TLD, ex.: mybrand.
• tlds (opcional, repetível) — ex.: ?tlds=com&tlds=io. Omitido → padrão para com, io, dev, app, co, net, org, me, ai, xyz.
• Sem necessidade de autenticação. Sempre use o host domainee.dev/api/..., não api.domainee.dev — a página de documentação menciona esse host, mas ele retorna 401 ("Missing Bearer token"); o endpoint funcional e com CORS habilitado está no mesmo domínio em domainee.dev/api.

Limite de taxa: 30 req/min, 500 req/dia por IP. A cota restante está nos cabeçalhos de resposta x-ratelimit-remaining-minute / x-ratelimit-remaining-day. Um 429 inclui Retry-After — exiba isso para o usuário em vez de tentar novamente em silêncio.

Sucesso:

{"ok":true,"data":{"name":"google","results":[
  {"tld":"com","fqdn":"google.com","available":false,"registrarHint":null},
  {"tld":"io","fqdn":"google.io","available":true,"registrarHint":null}
]}}

Erro (ex.: name ausente):

{"ok":false,"error":{"code":"missing_param","message":"Query parameter `name` is required (e.g. ?name=mybrand)"}}

Um TLD não reconhecido não é um erro — ele apenas retorna com um array results vazio.

Uma consulta ao registro por TLD também pode expirar. A entrada desse TLD terá então "available":null e um registrarHint explicando o motivo (ex.: "The operation was aborted due to timeout"), enquanto ok permanece true e os outros TLDs na mesma resposta não são afetados. Trate null como desconhecido, não como disponível ou ocupado — mostre-o como uma linha separada "não foi possível verificar" em vez de advinhar. Se todos os TLDs na resposta vierem como null de uma vez, isso é um soluço transitório na requisição inteira, não 10 timeouts coincidentes — tente a chamada novamente uma vez antes de relatar um resultado totalmente desconhecido ao usuário.

API de nome de pacote npm

GET https://registry.npmjs.org/<nome>

Sem autenticação, sem cabeçalhos de limite de taxa para se preocupar na prática. 200 = nome ocupado (um pacote real existe), 404 = livre. Para nomes com escopo (@scope/name), codifique a barra na URL: https://registry.npmjs.org/@scope%2Fname.

API de usuário/org GitHub

GET https://api.github.com/users/<nome>

Sem autenticação necessária. 200 = ocupado, 404 = livre. Requisições não autenticadas são limitadas a 60/hora por IP (cabeçalho x-ratelimit-remaining) — o suficiente para algumas verificações, mas não em loop sobre uma grande lista de nomes candidatos.

Fluxo de Trabalho

1. Remova qualquer TLD que o usuário já digitou para obter o nome puro.
2. Se o usuário está apenas perguntando sobre um domínio, chame apenas a API de domínio. Se ele estiver nomeando um projeto/startup/pacote/ferramenta, execute todas as três verificações (domínio, npm, GitHub) para aquele único nome — essa combinação é o real objetivo do skill, não domínios isoladamente.
3. Chame a API de domínio. Se o usuário não especificou TLDs específicos, omita tlds para obter o conjunto padrão de 10 extensões.
4. Mostre um resumo combinado: uma tabela de TLDs (disponível ✅ / ocupado ❌ / desconhecido-timeout ⚠️, a partir do registrarHint), mais uma linha cada para npm e GitHub (✅/❌).
5. Pergunte uma vez se deseja verificar mais TLDs (sugira alguns já não cobertos, ex.: .ai, .so, um ccTLD) — não pergunte novamente para o mesmo nome a menos que o usuário o mencione de novo.
6. Se ele nomear mais TLDs, repita a chamada de domínio com apenas esses tlds e mostre os novos resultados.

Handles de redes sociais (X, Instagram, etc.) são deliberadamente não incluídos — nenhuma dessas plataformas expõe uma verificação de disponibilidade gratuita e não autenticada; raspar páginas de perfil é não confiável e contra a maioria de seus termos. Diga isso se perguntado, em vez de advinhar a partir de uma raspagem.

Exemplo

curl -s "https://domainee.dev/api/v1/tools/domain-availability-checker?name=mybrand&tlds=com&tlds=io&tlds=ai"
curl -s -o /dev/null -w "%{http_code}" "https://registry.npmjs.org/mybrand"
curl -s -o /dev/null -w "%{http_code}" "https://api.github.com/users/mybrand"

Erros Comuns

• Usar api.domainee.dev — host errado, retorna 401. Use domainee.dev/api/....
• Tratar um array results vazio como falha — significa que o TLD não foi reconhecido, não um erro.
• Tentar novamente imediatamente após 429 — respeite Retry-After e avise o usuário, não faça loop.
• Verificar npm/GitHub para uma pergunta simples "este domínio está livre?" — só inclua essas verificações quando o usuário estiver realmente nomeando algo, não para toda consulta de domínio.
• Afirmar que verifica handles de redes sociais — não existe API gratuita confiável para isso; diga que está fora do escopo.