slick-address-kr 1.0.2 → 1.0.4

package/README.md

@@ -17,19 +17,35 @@ Korean address search library using official road address API - No popup require
 - ⌨️ **키보드 네비게이션**: 화살표 키로 결과 선택, 엔터로 적용 - 마우스 없이 빠른 입력!
 - 🔒 **TypeScript 지원**: 완전한 타입 정의 제공
 - 🌐 **프레임워크 무관**: Vanilla JS, React, Vue 등 어디서나 사용 가능
+- 📦 **모든 패키지 매니저 지원**: npm, yarn, pnpm, bun, deno 모두 호환
 
 ## 설치
 
+### npm
 ```bash
 npm install slick-address-kr
 ```
 
-또는
-
+### yarn
 ```bash
 yarn add slick-address-kr
 ```
 
+### pnpm
+```bash
+pnpm add slick-address-kr
+```
+
+### bun
+```bash
+bun add slick-address-kr
+```
+
+### deno
+```typescript
+import { KoreanAddressFinder } from "npm:slick-address-kr@1.0.4";
+```
+
 ## 빠른 시작
 
 ### 1. 기본 사용 (Vanilla JavaScript)
@@ -414,13 +430,24 @@ MIT License - 자유롭게 사용하세요!
 
 ## 문제 해결
 
+### "승인되지 않은 KEY 입니다" 오류가 나요
+
+이 라이브러리는 **API 키가 필수**입니다. 키 없이 사용하면 동작하지 않습니다.
+
+1. [행정안전부 도로명주소 OpenAPI](https://business.juso.go.kr/addrlink/openApi/searchApi.do)에서 **"검색 API"** 키를 직접 발급받으세요. (팝업 API 아님!)
+2. 발급받은 키를 `apiKey` 옵션으로 전달하세요:
+   ```js
+   new KoreanAddressFinder({ apiKey: '발급받은_본인_키', /* ... */ });
+   ```
+3. 행정안전부 **개발용(dev) 키는 발급 후 일정 기간이 지나면 만료**됩니다. 만료 시 새로 발급받으세요.
+
 ### CORS 에러가 발생해요
 
 행정안전부 API는 CORS를 지원합니다. 만약 에러가 발생한다면:
 
 1. API 키가 올바른지 확인
 2. ⚠️ **중요: API 발급 시 "검색 API"로 발급받았는지 확인** (팝업 API가 아님!)
-3. 도메인이 승인된 도메인인지 확인
+3. **키 발급 시 등록한 도메인에서만 호출이 허용됩니다.** 사용할 도메인(예: `localhost`, 실제 서비스 도메인)을 juso.go.kr에 등록했는지 확인하세요.
 4. HTTPS 사용 권장
 
 ### 검색 결과가 나오지 않아요

package/dist/address-finder.d.ts

@@ -53,6 +53,10 @@ export declare class KoreanAddressFinder {
      * 에러 표시
      */
     private showError;
+    /**
+     * HTML 특수문자 이스케이프 (XSS 방지)
+     */
+    private escapeHtml;
     /**
      * 컴포넌트 제거
      */

package/dist/address-finder.js

@@ -91,7 +91,7 @@ export class KoreanAddressFinder {
         const searchBtn = this.container.querySelector('.kaf-search-btn');
         searchBtn?.addEventListener('click', () => this.handleSearch());
         // 검색 입력 엔터키
-        this.searchInput?.addEventListener('keypress', (e) => {
+        this.searchInput?.addEventListener('keydown', (e) => {
             if (e.key === 'Enter') {
                 this.handleSearch();
             }
@@ -156,14 +156,14 @@ export class KoreanAddressFinder {
         <div class="kaf-result-item" data-index="${index}">
           <div class="kaf-result-main">
             <span class="kaf-result-type">도로명</span>
-            <span class="kaf-result-address">${result.roadAddress}</span>
+            <span class="kaf-result-address">${this.escapeHtml(result.roadAddress)}</span>
           </div>
           <div class="kaf-result-sub">
             <span class="kaf-result-type">지번</span>
-            <span class="kaf-result-address">${result.jibunAddress}</span>
+            <span class="kaf-result-address">${this.escapeHtml(result.jibunAddress)}</span>
           </div>
-          <div class="kaf-result-zipcode">우편번호: ${result.zipCode}</div>
-          ${result.buildingName ? `<div class="kaf-result-building">${result.buildingName}</div>` : ''}
+          <div class="kaf-result-zipcode">우편번호: ${this.escapeHtml(result.zipCode)}</div>
+          ${result.buildingName ? `<div class="kaf-result-building">${this.escapeHtml(result.buildingName)}</div>` : ''}
         </div>
       `).join('');
             // 결과 항목 클릭 이벤트
@@ -182,10 +182,10 @@ export class KoreanAddressFinder {
             selectedContainer.innerHTML = `
         <div class="kaf-selected-content">
           <div class="kaf-selected-main">
-            <strong>도로명:</strong> ${address.roadAddress}
+            <strong>도로명:</strong> ${this.escapeHtml(address.roadAddress)}
           </div>
           <div class="kaf-selected-sub">
-            <strong>우편번호:</strong> ${address.zipCode}
+            <strong>우편번호:</strong> ${this.escapeHtml(address.zipCode)}
           </div>
         </div>
       `;
@@ -235,6 +235,17 @@ export class KoreanAddressFinder {
             this.openResults();
         }
     }
+    /**
+     * HTML 특수문자 이스케이프 (XSS 방지)
+     */
+    escapeHtml(value) {
+        return String(value ?? '')
+            .replace(/&/g, '&amp;')
+            .replace(/</g, '&lt;')
+            .replace(/>/g, '&gt;')
+            .replace(/"/g, '&quot;')
+            .replace(/'/g, '&#39;');
+    }
     /**
      * 컴포넌트 제거
      */

package/dist/api-client.js

@@ -5,8 +5,9 @@
 export class AddressApiClient {
     constructor(apiKey) {
         this.apiUrl = 'https://business.juso.go.kr/addrlink/addrLinkApi.do';
-        // API 키가 없는 경우 공개 테스트 키 사용 (실제 서비스에서는 발급받아야 함)
-        this.confmKey = apiKey || 'devU01TX0FVVEgyMDI1MDExMDE1MTY0MTExNTM2MjY=';
+        // API 키는 필수입니다. 행정안전부 도로명주소 사이트에서 직접 발급받아야 합니다.
+        // https://business.juso.go.kr/addrlink/openApi/searchApi.do
+        this.confmKey = apiKey || '';
     }
     /**
      * 주소 검색
@@ -19,6 +20,10 @@ export class AddressApiClient {
         if (!keyword || keyword.trim().length === 0) {
             return { results: [], totalCount: 0 };
         }
+        if (!this.confmKey) {
+            throw new Error('API 키가 설정되지 않았습니다. KoreanAddressFinder 생성 시 apiKey 옵션을 전달하세요. ' +
+                '키 발급: https://business.juso.go.kr/addrlink/openApi/searchApi.do');
+        }
         try {
             const params = new URLSearchParams({
                 confmKey: this.confmKey,

package/korean-address-finder.js

@@ -14,6 +14,18 @@
   // API 설정
   const API_URL = 'https://business.juso.go.kr/addrlink/addrLinkApi.do';
 
+  /**
+   * HTML 특수문자 이스케이프 (XSS 방지)
+   */
+  function escapeHtml(value) {
+    return String(value == null ? '' : value)
+      .replace(/&/g, '&')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&#39;');
+  }
+
   /**
    * 주소 검색 클래스
    */
@@ -28,7 +40,10 @@
       this.debounceTimer = null; // 디바운스 타이머
 
       if (!this.apiKey) {
-        console.warn('⚠️ API 키가 설정되지 않았습니다. config.js 파일을 확인하세요.');
+        console.warn(
+          '⚠️ API 키가 설정되지 않았습니다. 행정안전부 도로명주소 사이트에서 "검색 API" 키를 발급받아 apiKey 옵션으로 전달하세요.\n' +
+          '키 발급: https://business.juso.go.kr/addrlink/openApi/searchApi.do'
+        );
       }
     }
 
@@ -203,7 +218,7 @@
       button.addEventListener('click', () => this.search(input.value));
 
       // 엔터키 검색
-      input.addEventListener('keypress', (e) => {
+      input.addEventListener('keydown', (e) => {
         if (e.key === 'Enter') {
           this.search(input.value);
         }
@@ -300,17 +315,20 @@
 
       let html = '';
       addresses.forEach(addr => {
+        const zipNo = escapeHtml(addr.zipNo);
+        const roadAddr = escapeHtml(addr.roadAddr);
+        const jibunAddr = escapeHtml(addr.jibunAddr);
         html += `
-          <div class="kaf-result-item" data-zipno="${addr.zipNo}" data-road="${addr.roadAddr}" data-jibun="${addr.jibunAddr}">
+          <div class="kaf-result-item" data-zipno="${zipNo}" data-road="${roadAddr}" data-jibun="${jibunAddr}">
             <div>
               <span class="kaf-result-type">도로명</span>
-              <span class="kaf-result-address">${addr.roadAddr}</span>
+              <span class="kaf-result-address">${roadAddr}</span>
             </div>
             <div style="margin-top: 4px;">
               <span class="kaf-result-type" style="background-color: #999;">지번</span>
-              <span class="kaf-result-address">${addr.jibunAddr}</span>
+              <span class="kaf-result-address">${jibunAddr}</span>
             </div>
-            <div class="kaf-result-zipcode">우편번호: ${addr.zipNo}</div>
+            <div class="kaf-result-zipcode">우편번호: ${zipNo}</div>
           </div>
         `;
       });
@@ -339,9 +357,9 @@
 
       selectedDiv.innerHTML = `
         <h3>✅ 선택된 주소</h3>
-        <p><strong>우편번호:</strong> ${address.zipCode}</p>
-        <p><strong>도로명 주소:</strong> ${address.roadAddress}</p>
-        <p><strong>지번 주소:</strong> ${address.jibunAddress}</p>
+        <p><strong>우편번호:</strong> ${escapeHtml(address.zipCode)}</p>
+        <p><strong>도로명 주소:</strong> ${escapeHtml(address.roadAddress)}</p>
+        <p><strong>지번 주소:</strong> ${escapeHtml(address.jibunAddress)}</p>
       `;
 
       selectedDiv.style.display = 'block';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slick-address-kr",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "행정안전부 도로명주소 API 기반 팝업 없는 한국 주소 검색 컴포넌트 (자동완성 지원) - Korean address search with autocomplete using official road address API",
   "main": "korean-address-finder.js",
   "types": "dist/index.d.ts",
@@ -27,7 +27,11 @@
     "행정안전부",
     "daum-address",
     "address-finder",
-    "road-address"
+    "road-address",
+    "pnpm",
+    "bun",
+    "deno",
+    "keyboard-navigation"
   ],
   "author": "Devguru-J",
   "license": "MIT",
@@ -49,7 +53,7 @@
     "config.example.js",
     "index.html",
     "README.md",
-    "README-KR.md",
+    "README.ko.md",
     "HOW-TO-USE.md",
     "API-KEY-GUIDE.md",
     "AUTOCOMPLETE-GUIDE.md",