Resetnak/domain-availability-skill

Verificación de Disponibilidad de Dominios

Descripción General

Verifica si un nombre está libre en tres superficies de las que suele depender la decisión de nombrar un proyecto: TLDs de dominio, nombre de paquete npm y usuario/org de GitHub. Cada verificación es una llamada API gratuita y sin clave — ejecútelas juntas cuando el usuario esté nombrando algo, o solo la verificación de dominio cuando eso sea lo que pidió.

API de Dominio

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

• name (obligatorio) — nombre del dominio sin TLD, por ejemplo, mimarca.
• tlds (opcional, repetible) — por ejemplo, ?tlds=com&tlds=io. Omitido → valores predeterminados: com, io, dev, app, co, net, org, me, ai, xyz.
• No se necesita autenticación. Utilice siempre el host domainee.dev/api/..., no api.domainee.dev — la página de documentación menciona ese host pero devuelve 401 ("Falta token Bearer"); el endpoint funcional y con CORS habilitado está en el mismo origen bajo domainee.dev/api.

Límite de tasa: 30 solicitudes/minuto, 500 solicitudes/día por IP. La cuota restante está en los encabezados de respuesta x-ratelimit-remaining-minute / x-ratelimit-remaining-day. Un 429 incluye Retry-After — muestre eso al usuario en lugar de reintentar silenciosamente.

Éxito:

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

Error (por ejemplo, falta name):

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

Un TLD no reconocido no es un error — solo devuelve un array results vacío.

Una búsqueda en el registro por TLD también puede agotar el tiempo de espera. La entrada de ese TLD tendrá entonces "available":null y un registrarHint explicando el motivo (por ejemplo, "The operation was aborted due to timeout"), mientras que ok sigue siendo true y los otros TLDs en la misma respuesta no se ven afectados. Trate null como desconocido, no como disponible u ocupado — muéstrelo como una fila separada "no se pudo verificar" en lugar de adivinar. Si todos los TLDs de la respuesta devuelven null a la vez, se trata de un problema transitorio de toda la solicitud, no de 10 tiempos de espera coincidentes — reintente la llamada una vez antes de informar un resultado completamente desconocido al usuario.

API de nombre de paquete npm

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

Sin autenticación, sin encabezados de límite de tasa que preocupen en la práctica. 200 = nombre ocupado (existe un paquete real), 404 = libre. Para nombres con ámbito (@scope/nombre), codifique la barra en URL: https://registry.npmjs.org/@scope%2Fnombre.

API de usuario/org de GitHub

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

No se necesita autenticación. 200 = ocupado, 404 = libre. Las solicitudes no autenticadas están limitadas a 60/hora por IP (encabezado x-ratelimit-remaining) — suficiente para un puñado de verificaciones, pero no recorra esto sobre una gran lista de nombres candidatos.

Flujo de trabajo

1. Elimine cualquier TLD que el usuario ya haya escrito para obtener el nombre desnudo.
2. Si el usuario solo pregunta por un dominio, llame solo a la API de dominio. Si está nombrando un proyecto/startup/paquete/herramienta, ejecute las tres verificaciones (dominio, npm, GitHub) para ese único nombre — esta combinación es el verdadero propósito de la habilidad, no los dominios de forma aislada.
3. Llame a la API de dominio. Si el usuario no especificó TLDs concretos, omita tlds para obtener el conjunto predeterminado de 10 extensiones.
4. Muestre un resumen combinado: una tabla de TLDs (disponible ✅ / ocupado ❌ / desconocido-tiempo de espera agotado ⚠️, basado en registrarHint), más una línea para npm y otra para GitHub (✅/❌).
5. Pregunte una vez si desea verificar más TLDs (sugiera algunos no cubiertos aún, por ejemplo, .ai, .so, un ccTLD) — no vuelva a preguntar por el mismo nombre a menos que el usuario lo mencione de nuevo.
6. Si menciona más TLDs, repita la llamada de dominio solo con esos tlds y muestre los nuevos resultados.

Los identificadores de redes sociales (X, Instagram, etc.) están deliberadamente no incluidos — ninguna de esas plataformas expone una verificación de disponibilidad gratuita y sin autenticación; raspar páginas de perfil no es fiable y va en contra de la mayoría de sus términos. Dígalo si le preguntan, en lugar de adivinar a partir de un raspado.

Ejemplo

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

Errores Comunes

• Usar api.domainee.dev — host incorrecto, devuelve 401. Use domainee.dev/api/....
• Tratar un array results vacío como fallo — significa que el TLD no fue reconocido, no es un error.
• Reintentar inmediatamente después de un 429 — respete Retry-After e informe al usuario, no recorra.
• Verificar npm/GitHub para una simple pregunta "¿está libre este dominio?" — solo incluya esas cuando el usuario esté realmente nombrando algo, no para cada búsqueda de dominio.
• Afirmar que se verifican identificadores de redes sociales — no existe una API gratuita fiable para eso; diga que está fuera del alcance.