JavaScript 및 TypeScript에서 Watch-IP 사용하기
@digitload/watch-ip-sdk(npm, v0.1.1)는 GET /v1/geo를 감싼 작은 클라이언트로, 모든 응답 필드에 대한 TypeScript 타입을 제공하며 런타임 의존성이 없습니다.
설치
Node.js 18 이상 또는 최신 브라우저가 필요합니다 — 이 패키지가 기반으로 하는 전역 fetch를 둘 다 제공합니다.
npm
npm install @digitload/watch-ip-sdk빠른 시작
공개 가능 키로 클라이언트를 생성하고 getGeo()를 호출하세요. 반환되는 GeoResponse는 완전히 타입이 지정되어 있습니다 — ip와 isEUCountry를 제외한 모든 필드는 null일 수 있으므로, 렌더링하기 전에 필드를 확인하세요.
TypeScript
import { WatchIP } from "@digitload/watch-ip-sdk";
const client = new WatchIP("wip_pub_xxxxxxxx");
const geo = await client.getGeo();
console.log(geo.country, geo.city, geo.timezone);오류 처리와 타임아웃
모든 실패 상황 — 거부된 요청(잘못된 키, 허용되지 않은 오리진, 속도 제한) 또는 네트워크 오류 — 은 status와 안정적인 code를 가진 WatchIPError를 던집니다. 내장된 타임아웃은 없으므로, 느린 요청을 직접 취소하려면 AbortController의 signal을 전달하세요.
TypeScript
import { WatchIP, WatchIPError } from "@digitload/watch-ip-sdk";
const client = new WatchIP("wip_pub_xxxxxxxx");
const controller = new AbortController();
setTimeout(() => controller.abort(), 5000);
try {
const geo = await client.getGeo({ signal: controller.signal });
} catch (err) {
if (err instanceof WatchIPError) {
console.error(err.code, err.status, err.message);
}
}선택적 필드
연결된 IP에 대한 역방향 DNS 조회를 추가하려면 include: ["hostname"]을 전달하세요. 추가 네트워크 홉이 발생하므로 선택적으로 제공되며, 실제로 이 필드를 사용할 때만 요청하세요.
TypeScript
const geo = await client.getGeo({ include: ["hostname"] });이 SDK가 지원하지 않는 것
이 패키지는 GET /v1/geo만 호출합니다. IP 조회, 이메일 검증, 위험도 확인에 대한 메서드는 없습니다 — 이들은 이 SDK가 사용하는 공개 가능 키가 아니라 시크릿 키로 인증하는 서버 간 엔드포인트입니다. HTTP를 직접 호출하세요 — IP 조회 레퍼런스와 인증 가이드를 참고하세요.