Resetnak/domain-availability-skill

도메인 사용 가능 여부 확인하기

개요

name이 프로젝트 이름을 정할 때 일반적으로 고려하는 세 가지 표면(도메인 TLD, npm 패키지 이름, GitHub 사용자명/조직)에서 사용 가능한지 확인합니다. 각 확인은 별도의 무료, 키 없는 API 호출로 이루어집니다 — 사용자가 이름을 정할 때는 세 가지를 함께 실행하고, 사용자가 도메인만 물어봤을 때는 도메인 확인만 수행하세요.

도메인 API

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

• name (필수) — TLD를 제외한 도메인 이름, 예: mybrand.
• tlds (선택, 반복 가능) — 예: ?tlds=com&tlds=io. 생략 시 기본값은 com, io, dev, app, co, net, org, me, ai, xyz입니다.
• 인증 필요 없음. 항상 호스트 domainee.dev/api/...를 사용하고 api.domainee.dev는 사용하지 마세요 — 문서 페이지에서 해당 호스트를 언급하지만 401 오류("Missing Bearer token")가 발생합니다; 작동하며 CORS가 활성화된 엔드포인트는 동일 출처의 domainee.dev/api 아래에 있습니다.

속도 제한: IP당 분당 30회, 일 500회. 남은 할당량은 응답 헤더 x-ratelimit-remaining-minute / x-ratelimit-remaining-day에 있습니다. 429 응답에는 Retry-After가 포함됩니다 — 이를 사용자에게 알리고 자동 재시도하지 마세요.

성공:

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

오류 (예: name 누락):

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

인식할 수 없는 TLD는 오류가 아닙니다 — 빈 results 배열로 반환됩니다.

TLD별 레지스트리 조회가 타임아웃될 수도 있습니다. 해당 TLD의 항목은 "available":null이 되고 registrarHint에 이유가 설명됩니다 (예: "The operation was aborted due to timeout"). ok는 true를 유지하며 동일한 응답의 다른 TLD에는 영향을 주지 않습니다. null은 알 수 없음으로 처리하고, 사용 가능 또는 사용 중으로 추측하지 말고 별도의 "확인할 수 없음" 행으로 표시하세요. 응답의 모든 TLD가 동시에 null로 반환된다면, 이는 10개의 우연한 타임아웃이 아니라 전체 요청의 일시적인 문제입니다 — 모든 결과가 알 수 없음으로 표시되기 전에 한 번 재시도하세요.

npm 패키지 이름 API

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

인증 불필요, 실제로 걱정할 속도 제한 헤더 없음. 200 = 이름 사용 중 (실제 패키지가 존재함), 404 = 사용 가능. 스코프가 있는 이름(@scope/name)의 경우 슬래시를 URL 인코딩하세요: https://registry.npmjs.org/@scope%2Fname.

GitHub 사용자명/조직 API

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

인증 불필요. 200 = 사용 중, 404 = 사용 가능. 인증되지 않은 요청의 경우 IP당 시간당 60회로 제한됩니다 (x-ratelimit-remaining 헤더) — 소수의 확인에는 문제없지만, 후보 이름 목록 전체를 반복해서 확인하지는 마세요.

워크플로우

1. 사용자가 이미 입력한 TLD를 제거하여 기본 name을 얻습니다.
2. 사용자가 단순히 도메인을 묻는 경우에만 도메인 API를 호출합니다. 사용자가 프로젝트/스타트업/패키지/도구의 이름을 정하는 중이라면 해당 name에 대해 세 가지 확인(도메인, npm, GitHub)을 모두 수행합니다 — 이 조합이 이 스킬의 실제 목적이며, 도메인만 확인하는 것이 아닙니다.
3. 도메인 API를 호출합니다. 사용자가 특정 TLD를 지정하지 않은 경우 tlds를 생략하여 기본 10개 확장자 세트를 사용합니다.
4. 하나의 통합 요약을 표시합니다: TLD 테이블(사용 가능 ✅ / 사용 중 ❌ / 알 수 없음-타임아웃 ⚠️, registrarHint 포함), 그리고 npm과 GitHub 각각에 대한 한 줄(✅/❌).
5. 더 많은 TLD를 확인할지 한 번 묻습니다 (아직 다루지 않은 몇 가지를 제안하세요, 예: .ai, .so, ccTLD) — 사용자가 다시 언급하지 않는 한 동일한 이름에 대해 다시 묻지 마세요.
6. 사용자가 더 많은 TLD를 지정하면 해당 tlds만 사용하여 도메인 호출을 반복하고 새 결과를 표시합니다.

소셜 핸들(X, Instagram 등)은 의도적으로 포함되지 않았습니다 — 해당 플랫폼 중 어느 것도 무료, 인증 없는 사용 가능 여부 확인을 제공하지 않습니다; 프로필 페이지를 스크래핑하는 것은 신뢰할 수 없으며 대부분의 이용 약관에 위배됩니다. 요청받으면 추측하지 말고 그 이유를 설명하세요.

예시

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"

흔한 실수

• api.domainee.dev 사용 — 잘못된 호스트, 401 반환. domainee.dev/api/...를 사용하세요.
• 빈 results 배열을 실패로 간주 — 인식되지 않은 TLD를 의미할 뿐 오류가 아닙니다.
• 429 직후 즉시 재시도 — Retry-After를 존중하고 사용자에게 알리며, 반복하지 마세요.
• 단순 "이 도메인 무료인가요?" 질문에 npm/GitHub 확인 — 모든 도메인 조회에 대해가 아니라 사용자가 실제로 이름을 정하는 중일 때만 사용하세요.
• 소셜 핸들을 확인한다고 주장 — 신뢰할 수 있는 무료 API가 없습니다; 범위 밖이라고 말하세요.