@cp949/japanpost-react 1.0.0 → 1.0.1

package/README.md

@@ -1,12 +1,8 @@
-<!-- This file is generated by `pnpm readme:package`. Edit docs/README.en.md and docs/README.ko.md instead. -->
-
 # @cp949/japanpost-react
 
-[English](#english) | [한국어](#한국어)
+[한국어 README](./README.ko.md)
 
----
-
-## English
+<!-- This file is generated by `pnpm readme:package`. Edit docs/README.en.md and docs/README.ko.md instead. -->
 
 React + TypeScript hooks and headless inputs for Japan postal-code and address
 lookup.
@@ -27,83 +23,112 @@ pnpm add @cp949/japanpost-react
 
 ```tsx
 import { useJapanPostalCode } from "@cp949/japanpost-react";
-import type { JapanAddressDataSource } from "@cp949/japanpost-react";
+import type {
+  JapanAddressDataSource,
+  JapanAddressRequestOptions,
+  JapanAddress,
+  Page,
+} from "@cp949/japanpost-react";
 import { createJapanAddressError } from "@cp949/japanpost-react";
 
 // The only supported integration model is a real server-backed flow.
 // Point the data source at your own backend API.
+// On beta-compatible backends, blank addresszip searches and postal-code misses
+// may return HTTP 200 with an empty page. Keep those as successful Page results.
+// The status mapping below applies only to non-OK responses.
+function isAbortError(error: unknown): boolean {
+  return error instanceof DOMException && error.name === "AbortError";
+}
+
+function resolveErrorCode(path: string, status: number) {
+  if (status === 404) {
+    return "not_found";
+  }
+
+  if (status === 504) {
+    return "timeout";
+  }
+
+  if (status === 400) {
+    return path === "/q/japanpost/searchcode"
+      ? "invalid_postal_code"
+      : "invalid_query";
+  }
+
+  return "data_source_error";
+}
+
+async function readPage(
+  path: string,
+  request: unknown,
+  options?: JapanAddressRequestOptions,
+): Promise<Page<JapanAddress>> {
+  let res: Response;
+
+  try {
+    res = await fetch(path, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+      },
+      body: JSON.stringify(request),
+      signal: options?.signal,
+    });
+  } catch (error) {
+    throw createJapanAddressError(
+      isAbortError(error) ? "timeout" : "network_error",
+      isAbortError(error) ? "Request timed out" : "Network request failed",
+      {
+        cause: error,
+      },
+    );
+  }
+
+  if (!res.ok) {
+    const message = `Request failed with status ${res.status}`;
+
+    throw createJapanAddressError(resolveErrorCode(path, res.status), message, {
+      status: res.status,
+    });
+  }
+
+  let payload: unknown;
+
+  try {
+    payload = await res.json();
+  } catch (error) {
+    throw createJapanAddressError(
+      "bad_response",
+      "Response payload was not valid JSON",
+      {
+        cause: error,
+      },
+    );
+  }
+
+  if (
+    typeof payload !== "object" ||
+    payload === null ||
+    !Array.isArray((payload as { elements?: unknown }).elements) ||
+    typeof (payload as { totalElements?: unknown }).totalElements !== "number" ||
+    typeof (payload as { pageNumber?: unknown }).pageNumber !== "number" ||
+    typeof (payload as { rowsPerPage?: unknown }).rowsPerPage !== "number"
+  ) {
+    throw createJapanAddressError(
+      "bad_response",
+      "Response payload must include a valid page payload",
+    );
+  }
+
+  return payload as Page<JapanAddress>;
+}
+
 const dataSource: JapanAddressDataSource = {
-  async lookupPostalCode(postalCode) {
-    const res = await fetch(`/searchcode/${postalCode}`);
-    if (!res.ok) {
-      const message = `Postal code lookup failed with status ${res.status}`;
-
-      if (res.status === 400) {
-        throw createJapanAddressError("invalid_postal_code", message, {
-          status: res.status,
-        });
-      }
-
-      if (res.status === 404) {
-        throw createJapanAddressError("not_found", message, {
-          status: res.status,
-        });
-      }
-
-      if (res.status === 504) {
-        throw createJapanAddressError("timeout", message, {
-          status: res.status,
-        });
-      }
-
-      throw createJapanAddressError("data_source_error", message, {
-        status: res.status,
-      });
-    }
-    const payload = await res.json();
-    if (!Array.isArray(payload.addresses)) {
-      throw createJapanAddressError(
-        "bad_response",
-        "Postal code lookup returned an invalid payload",
-      );
-    }
-    return payload.addresses;
+  async lookupPostalCode(request, options) {
+    return readPage(`/q/japanpost/searchcode`, request, options);
   },
-  async searchAddress(query) {
-    const res = await fetch(`/addresszip?q=${encodeURIComponent(query)}`);
-    if (!res.ok) {
-      const message = `Address search failed with status ${res.status}`;
-
-      if (res.status === 400) {
-        throw createJapanAddressError("invalid_query", message, {
-          status: res.status,
-        });
-      }
-
-      if (res.status === 404) {
-        throw createJapanAddressError("not_found", message, {
-          status: res.status,
-        });
-      }
-
-      if (res.status === 504) {
-        throw createJapanAddressError("timeout", message, {
-          status: res.status,
-        });
-      }
-
-      throw createJapanAddressError("data_source_error", message, {
-        status: res.status,
-      });
-    }
-    const payload = await res.json();
-    if (!Array.isArray(payload.addresses)) {
-      throw createJapanAddressError(
-        "bad_response",
-        "Address search returned an invalid payload",
-      );
-    }
-    return payload.addresses;
+  async searchAddress(request, options) {
+    return readPage(`/q/japanpost/addresszip`, request, options);
   },
 };
 
@@ -119,7 +144,8 @@ export function PostalForm() {
           {error.code}: {error.message}
         </p>
       )}
-      {data?.addresses.map((addr) => (
+      <p>Total results: {data?.totalElements ?? 0}</p>
+      {data?.elements.map((addr) => (
         <p key={addr.postalCode + addr.address}>{addr.address}</p>
       ))}
     </div>
@@ -127,6 +153,12 @@ export function PostalForm() {
 }
 ```
 
+The sample `resolveErrorCode()` helper only classifies non-OK responses. In the
+current beta-compatible contract, blank address-search requests and postal-code
+misses may still succeed with `200` plus an empty page, while `404 -> not_found`
+remains a backend-specific choice for servers that intentionally surface misses
+as errors.
+
 ## Exports
 
 - `normalizeJapanPostalCode`
@@ -139,7 +171,8 @@ export function PostalForm() {
 - `useJapanAddress`
 - `PostalCodeInput`
 - `AddressSearchInput`
-- Public types including `JapanAddress` and `JapanAddressDataSource`
+- Public types including `JapanAddress`, `JapanAddressDataSource`,
+  `JapanPostSearchcodeRequest`, `JapanPostAddresszipRequest`, and `Page`
 - Request options type: `JapanAddressRequestOptions`
 
 ## Utility Notes
@@ -152,7 +185,8 @@ without inserting a hyphen.
 
 ### useJapanPostalCode
 
-Looks up addresses by postal code.
+Looks up addresses by postal code. The hook accepts `3-7` digits and uses
+prefix search when the input has `3-6` digits.
 
 ```tsx
 const { loading, data, error, search, reset } = useJapanPostalCode({
@@ -171,6 +205,11 @@ const { loading, data, error, search, reset } = useJapanAddressSearch({
 });
 ```
 
+The hook still performs client-side pre-validation for blank queries and
+returns `invalid_query` before sending a request. That validation is a UX
+helper only and does not replace server-side validation or server-side
+contract handling.
+
 ### useJapanAddress
 
 Combines postal-code lookup and keyword search into one hook.
@@ -182,10 +221,28 @@ const { loading, data, error, searchByPostalCode, searchByKeyword, reset } =
 
 All hooks require `dataSource` at runtime.
 
+The hook public APIs stay string-based:
+
+- `useJapanPostalCode().search(value: string)`
+- `useJapanAddressSearch().search(query: string)`
+- `useJapanAddress().searchByPostalCode(value: string)`
+- `useJapanAddress().searchByKeyword(query: string)`
+
+Internally, the hooks build request objects before calling the data source:
+
+- postal-code lookup: `{ value, pageNumber: 0, rowsPerPage: 100 }`
+- address search: `{ freeword, pageNumber: 0, rowsPerPage: 100 }`
+
+Optional request flags such as `includeCityDetails` and
+`includePrefectureDetails` are omitted unless your own data source
+implementation sets them explicitly.
+
 ## Error Handling Notes
 
-`JapanAddressDataSource` should return `JapanAddress[]` directly from both
-methods. The hooks wrap those arrays into lookup/search result objects.
+`JapanAddressDataSource` should return `Page<JapanAddress>` directly from both
+methods. Hooks preserve that page payload as-is, so consumers can read
+`data.elements`, `data.totalElements`, `data.pageNumber`, and
+`data.rowsPerPage` directly.
 
 Both methods may also receive an optional second argument:
 
@@ -203,16 +260,20 @@ Recommended error-code mapping:
 | Situation | Recommended code |
 | --- | --- |
 | Invalid postal code input | `invalid_postal_code` |
-| Blank keyword input | `invalid_query` |
+| Blank keyword input in hook-side pre-validation | `invalid_query` |
 | Network failure | `network_error` |
 | Request aborted / timeout | `timeout` |
-| No matching addresses | `not_found` |
+| No matching addresses on backends that surface misses as errors | `not_found` |
 | Malformed success payload | `bad_response` |
 | Other backend failures | `data_source_error` |
 
-In this repository's reference demo flow, the sample `dataSource` maps `400
-/searchcode/...` to `invalid_postal_code`, `400 /addresszip?...` to
-`invalid_query`, `404` to `not_found`, and `504` to `timeout`.
+In this repository's reference demo flow, the sample `dataSource` classifies
+failed requests by HTTP status code only. Current beta-compatible flows may
+return `200` with an empty page for both blank `addresszip` requests and
+postal-code misses, and those should stay successful page results. Other
+`400` responses can still map to `invalid_query`, `404` remains useful for
+backends that intentionally surface misses as errors, and `504` maps to
+`timeout`.
 
 ## Headless Components
 
@@ -251,250 +312,3 @@ the upstream lookup request timed out. Both cases still map cleanly to the
 Use your server-side API from the `dataSource` implementation, and keep token
 exchange plus upstream signing on the server. React hooks and UI components
 should stay in client components.
-
----
-
-## 한국어
-
-React + TypeScript 기반의 일본 우편번호/주소 검색 훅과 headless 입력
-컴포넌트 라이브러리입니다.
-
-이 문서는 배포 패키지 사용 가이드입니다. `pnpm demo:full` 같은 저장소 수준 보조
-스크립트는 현재 Linux/WSL 계열 셸 환경을 전제로 하며, 자세한 내용은 루트 README에서 다룹니다.
-
-## 설치
-
-```bash
-pnpm add @cp949/japanpost-react
-```
-
-- 지원 React 버전: React 18, React 19
-
-## 빠른 시작
-
-```tsx
-import { useJapanPostalCode } from "@cp949/japanpost-react";
-import type { JapanAddressDataSource } from "@cp949/japanpost-react";
-import { createJapanAddressError } from "@cp949/japanpost-react";
-
-// 현재 지원 방식은 실제 서버 연동뿐입니다.
-// 앱의 백엔드 API 경로에 맞게 dataSource를 연결하세요.
-const dataSource: JapanAddressDataSource = {
-  async lookupPostalCode(postalCode) {
-    const res = await fetch(`/searchcode/${postalCode}`);
-    if (!res.ok) {
-      const message = `Postal code lookup failed with status ${res.status}`;
-
-      if (res.status === 400) {
-        throw createJapanAddressError("invalid_postal_code", message, {
-          status: res.status,
-        });
-      }
-
-      if (res.status === 404) {
-        throw createJapanAddressError("not_found", message, {
-          status: res.status,
-        });
-      }
-
-      if (res.status === 504) {
-        throw createJapanAddressError("timeout", message, {
-          status: res.status,
-        });
-      }
-
-      throw createJapanAddressError("data_source_error", message, {
-        status: res.status,
-      });
-    }
-    const payload = await res.json();
-    if (!Array.isArray(payload.addresses)) {
-      throw createJapanAddressError(
-        "bad_response",
-        "Postal code lookup returned an invalid payload",
-      );
-    }
-    return payload.addresses;
-  },
-  async searchAddress(query) {
-    const res = await fetch(`/addresszip?q=${encodeURIComponent(query)}`);
-    if (!res.ok) {
-      const message = `Address search failed with status ${res.status}`;
-
-      if (res.status === 400) {
-        throw createJapanAddressError("invalid_query", message, {
-          status: res.status,
-        });
-      }
-
-      if (res.status === 404) {
-        throw createJapanAddressError("not_found", message, {
-          status: res.status,
-        });
-      }
-
-      if (res.status === 504) {
-        throw createJapanAddressError("timeout", message, {
-          status: res.status,
-        });
-      }
-
-      throw createJapanAddressError("data_source_error", message, {
-        status: res.status,
-      });
-    }
-    const payload = await res.json();
-    if (!Array.isArray(payload.addresses)) {
-      throw createJapanAddressError(
-        "bad_response",
-        "Address search returned an invalid payload",
-      );
-    }
-    return payload.addresses;
-  },
-};
-
-export function PostalForm() {
-  const { loading, data, error, search } = useJapanPostalCode({ dataSource });
-
-  return (
-    <div>
-      <button onClick={() => void search("100-0001")}>조회</button>
-      {loading && <p>조회 중...</p>}
-      {error && (
-        <p>
-          {error.code}: {error.message}
-        </p>
-      )}
-      {data?.addresses.map((addr) => (
-        <p key={addr.postalCode + addr.address}>{addr.address}</p>
-      ))}
-    </div>
-  );
-}
-```
-
-## Exports
-
-- `normalizeJapanPostalCode`
-- `formatJapanPostalCode`
-- `normalizeJapanPostAddressRecord`
-- `isValidJapanPostalCode`
-- `createJapanAddressError`
-- `useJapanPostalCode`
-- `useJapanAddressSearch`
-- `useJapanAddress`
-- `PostalCodeInput`
-- `AddressSearchInput`
-- `JapanAddress`, `JapanAddressDataSource`를 포함한 공개 타입
-- 요청 옵션 타입: `JapanAddressRequestOptions`
-
-## 유틸리티 메모
-
-`formatJapanPostalCode()`는 정규화된 값이 정확히 7자리일 때만 하이픈을 넣습니다.
-그 외 길이에서는 하이픈을 추가하지 않고 숫자만 남긴 값을 그대로 반환합니다.
-
-## Hooks
-
-### useJapanPostalCode
-
-우편번호로 주소를 조회합니다.
-
-```tsx
-const { loading, data, error, search, reset } = useJapanPostalCode({
-  dataSource,
-});
-```
-
-### useJapanAddressSearch
-
-자유 형식 키워드로 주소를 검색하며 `debounceMs`를 지원합니다.
-
-```tsx
-const { loading, data, error, search, reset } = useJapanAddressSearch({
-  dataSource,
-  debounceMs: 300,
-});
-```
-
-### useJapanAddress
-
-우편번호 조회와 키워드 검색을 하나의 훅으로 합칩니다.
-
-```tsx
-const { loading, data, error, searchByPostalCode, searchByKeyword, reset } =
-  useJapanAddress({ dataSource, debounceMs: 300 });
-```
-
-모든 훅은 런타임에서 `dataSource`가 필요합니다.
-
-## 에러 처리 메모
-
-`JapanAddressDataSource`의 두 메서드는 모두 `JapanAddress[]`를 직접
-반환해야 합니다. 각 훅은 그 배열을 받아 `{ postalCode, addresses }`,
-`{ query, addresses }` 형태의 결과 객체를 조합합니다.
-
-두 메서드는 선택적인 두 번째 인자도 받을 수 있습니다.
-
-```ts
-type JapanAddressRequestOptions = {
-  signal?: AbortSignal;
-};
-```
-
-훅은 superseded 요청, `reset()`, unmount 정리 상황에서 이전 요청을 취소할 수
-있도록 `signal`을 전달합니다. 백엔드 레이어가 abort를 지원하면 그대로 활용할 수
-있습니다.
-
-권장 에러 코드 매핑:
-
-| 상황 | 권장 코드 |
-| --- | --- |
-| 잘못된 우편번호 입력 | `invalid_postal_code` |
-| 빈 주소 검색어 | `invalid_query` |
-| 네트워크 실패 | `network_error` |
-| 요청 중단 / 타임아웃 | `timeout` |
-| 검색 결과 없음 | `not_found` |
-| 성공 응답 shape 이상 | `bad_response` |
-| 그 외 백엔드 오류 | `data_source_error` |
-
-이 저장소의 참고 demo 흐름에서는 예시 `dataSource`가 `400 /searchcode/...`를
-`invalid_postal_code`, `400 /addresszip?...`를 `invalid_query`, `404`를
-`not_found`, `504`를 `timeout`으로 매핑합니다.
-
-## Headless 컴포넌트
-
-`PostalCodeInput`, `AddressSearchInput`은 스타일 없이 동작과 DOM 구조만
-제공하므로, 앱의 디자인 시스템에 맞게 직접 꾸밀 수 있습니다.
-
-두 컴포넌트는 네이티브 props 전달도 지원합니다.
-
-- `inputProps`: 실제 `<input />`에 전달
-- `buttonProps`: 실제 `<button />`에 전달
-
-따라서 `id`, `name`, `placeholder`, `aria-*`, `autoComplete`, `className`,
-폼 연동용 속성을 직접 넘길 수 있습니다. `PostalCodeInput`은 별도 override가
-없으면 기본적으로 `inputMode="numeric"`를 사용합니다.
-
-## Data Source와 서버 연동
-
-이 패키지는 자체 백엔드 서버와 함께 사용하는 것을 권장합니다. Japan Post
-공식 연동은 토큰 기반 인증을 사용하므로, 브라우저에서 업스트림 자격증명을
-직접 보관하면 안 됩니다. 현재 지원 방식은 실제 서버 연동뿐입니다.
-
-이 저장소의 `apps/minimal-api`는 로컬 기준 참고 서버 구현입니다. Japan Post
-API ver 2.0을 감싸며, 로컬 개발과 통합 확인 용도로 쓰는 구성을 목표로
-합니다. demo의 `/minimal-api` 경로는 개발 편의를 위한 로컬 경로 연결입니다.
-업스트림 payload에 구조화된 주소 필드와 원본 전체 주소 문자열인 `address`가 함께
-있더라도, 참고 서버는 둘을 그대로 이어붙이지 않고 중복 없는 표시 주소를
-우선 사용합니다.
-
-timeout 메시지는 토큰 발급 단계와 실제 조회 단계 중 어느 쪽에서 timeout이
-발생했는지에 따라 달라질 수 있지만, 두 경우 모두 `timeout` 코드로 다루면
-됩니다.
-
-## SSR
-
-`dataSource` 구현에서는 서버 측 API를 사용하고, 토큰 교환과 업스트림 서명은
-서버에서만 처리하세요. React 훅과 UI 컴포넌트는 클라이언트 컴포넌트에서
-사용하는 것이 안전합니다.

package/dist/components/AddressSearchInput.d.ts

@@ -2,6 +2,7 @@ import { AddressSearchInputProps } from '../core/types';
 /**
  * 스타일 의존성이 없는 최소한의 주소 키워드 검색 입력 컴포넌트.
  * value를 전달하면 제어 모드, 전달하지 않으면 비제어 모드로 동작한다.
+ * 검색 시 trim 처리를 내부에서 수행해 공백만 다른 입력이 별도 쿼리로 번지지 않게 한다.
  */
 export declare function AddressSearchInput({ defaultValue, value, disabled, label, buttonLabel, inputProps, buttonProps, onChange, onSearch, }: AddressSearchInputProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=AddressSearchInput.d.ts.map

package/dist/components/AddressSearchInput.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AddressSearchInput.d.ts","sourceRoot":"","sources":["../../src/components/AddressSearchInput.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAE7D;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,YAAiB,EACjB,KAAK,EACL,QAAQ,EACR,KAAyB,EACzB,WAAsB,EACtB,UAAU,EACV,WAAW,EACX,QAAQ,EACR,QAAQ,GACT,EAAE,uBAAuB,2CA4CzB"}
+{"version":3,"file":"AddressSearchInput.d.ts","sourceRoot":"","sources":["../../src/components/AddressSearchInput.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAE7D;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,YAAiB,EACjB,KAAK,EACL,QAAQ,EACR,KAAyB,EACzB,WAAsB,EACtB,UAAU,EACV,WAAW,EACX,QAAQ,EACR,QAAQ,GACT,EAAE,uBAAuB,2CA4CzB"}

package/dist/components/PostalCodeInput.d.ts

@@ -2,6 +2,7 @@ import { PostalCodeInputProps } from '../core/types';
 /**
  * 스타일 의존성이 없는 최소한의 우편번호 입력 컴포넌트.
  * value를 전달하면 제어 모드, 전달하지 않으면 비제어 모드로 동작한다.
+ * 제출 시에는 표시 형식이 아니라 정규화된 숫자 문자열을 콜백에 넘기는 것이 핵심 계약이다.
  */
 export declare function PostalCodeInput({ defaultValue, value, disabled, label, buttonLabel, inputProps, buttonProps, onChange, onSearch, }: PostalCodeInputProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=PostalCodeInput.d.ts.map

package/dist/components/PostalCodeInput.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PostalCodeInput.d.ts","sourceRoot":"","sources":["../../src/components/PostalCodeInput.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAE1D;;;GAGG;AACH,wBAAgB,eAAe,CAAC,EAC9B,YAAiB,EACjB,KAAK,EACL,QAAQ,EACR,KAAqB,EACrB,WAAsB,EACtB,UAAU,EACV,WAAW,EACX,QAAQ,EACR,QAAQ,GACT,EAAE,oBAAoB,2CA6CtB"}
+{"version":3,"file":"PostalCodeInput.d.ts","sourceRoot":"","sources":["../../src/components/PostalCodeInput.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAE1D;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,EAC9B,YAAiB,EACjB,KAAK,EACL,QAAQ,EACR,KAAqB,EACrB,WAAsB,EACtB,UAAU,EACV,WAAW,EACX,QAAQ,EACR,QAAQ,GACT,EAAE,oBAAoB,2CA8CtB"}

package/dist/core/errors.d.ts

@@ -1,7 +1,8 @@
 import { JapanAddressError, JapanAddressErrorCode } from './types';
 /**
- * 라이브러리 전용 에러 객체를 생성한다.
- * name과 code를 일관되게 설정해 catch 블록에서 타입 좁히기가 쉽도록 한다.
+ * 라이브러리 전반에서 공통으로 쓰는 오류 객체 생성기다.
+ * 브라우저 fetch 오류, validation 오류, data source 오류를 모두 같은 표면으로 맞춰
+ * 소비자가 code/status만으로 분기할 수 있게 한다.
  */
 export declare function createJapanAddressError(code: JapanAddressErrorCode, message: string, options?: {
     cause?: unknown;

package/dist/core/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAExE;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,qBAAqB,EAC3B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7C,iBAAiB,CAQnB"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAExE;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,qBAAqB,EAC3B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7C,iBAAiB,CAQnB"}

package/dist/core/normalizers.d.ts

@@ -1,7 +1,7 @@
 import { JapanAddress, NormalizedJapanAddressRecord } from './types';
 /**
  * 정규화된 내부 주소 레코드를 라이브러리 공개 JapanAddress 형태로 변환한다.
- * address는 도도부현·시구정촌·동·상세주소를 순서대로 이어붙인 문자열이다.
+ * address는 표시용 convenience 필드이므로, 구조화된 필드와 같은 순서를 유지해 예측 가능성을 보장한다.
  */
 export declare function normalizeJapanPostAddressRecord(record: NormalizedJapanAddressRecord): JapanAddress;
 //# sourceMappingURL=normalizers.d.ts.map

package/dist/core/normalizers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"normalizers.d.ts","sourceRoot":"","sources":["../../src/core/normalizers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,4BAA4B,EAAE,MAAM,SAAS,CAAC;AAU1E;;;GAGG;AACH,wBAAgB,+BAA+B,CAC7C,MAAM,EAAE,4BAA4B,GACnC,YAAY,CAoBd"}
+{"version":3,"file":"normalizers.d.ts","sourceRoot":"","sources":["../../src/core/normalizers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,4BAA4B,EAAE,MAAM,SAAS,CAAC;AAe1E;;;GAGG;AACH,wBAAgB,+BAA+B,CAC7C,MAAM,EAAE,4BAA4B,GACnC,YAAY,CAoBd"}