@cp949/japanpost-react 1.0.0 → 1.0.1

package/README.ko.md

@@ -0,0 +1,309 @@
+# @cp949/japanpost-react
+
+[English README](./README.md)
+
+<!-- This file is generated by `pnpm readme:package`. Edit docs/README.en.md and docs/README.ko.md instead. -->
+
+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,
+  JapanAddressRequestOptions,
+  JapanAddress,
+  Page,
+} from "@cp949/japanpost-react";
+import { createJapanAddressError } from "@cp949/japanpost-react";
+
+// 현재 지원 방식은 실제 서버 연동뿐입니다.
+// 앱의 백엔드 API 경로에 맞게 dataSource를 연결하세요.
+// 현재 beta 호환 백엔드에서는 빈 addresszip 검색과 우편번호 miss가
+// HTTP 200 + empty page로 올 수 있으며, 이런 경우는 정상 Page 결과로 유지합니다.
+// 아래 status 매핑은 non-OK 응답에만 적용됩니다.
+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(request, options) {
+    return readPage(`/q/japanpost/searchcode`, request, options);
+  },
+  async searchAddress(request, options) {
+    return readPage(`/q/japanpost/addresszip`, request, options);
+  },
+};
+
+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>
+      )}
+      <p>전체 결과 수: {data?.totalElements ?? 0}</p>
+      {data?.elements.map((addr) => (
+        <p key={addr.postalCode + addr.address}>{addr.address}</p>
+      ))}
+    </div>
+  );
+}
+```
+
+예시 `resolveErrorCode()` helper는 non-OK 응답만 분류합니다. 현재 beta 호환
+계약에서는 빈 주소 검색 요청과 우편번호 miss가 `200 + empty page`로 정상
+성공할 수 있고, `404 -> not_found`는 miss를 오류로 노출하는 백엔드에서만
+선택적으로 쓰면 됩니다.
+
+## Exports
+
+- `normalizeJapanPostalCode`
+- `formatJapanPostalCode`
+- `normalizeJapanPostAddressRecord`
+- `isValidJapanPostalCode`
+- `createJapanAddressError`
+- `useJapanPostalCode`
+- `useJapanAddressSearch`
+- `useJapanAddress`
+- `PostalCodeInput`
+- `AddressSearchInput`
+- `JapanAddress`, `JapanAddressDataSource`, `JapanPostSearchcodeRequest`,
+  `JapanPostAddresszipRequest`, `Page`를 포함한 공개 타입
+- 요청 옵션 타입: `JapanAddressRequestOptions`
+
+## 유틸리티 메모
+
+`formatJapanPostalCode()`는 정규화된 값이 정확히 7자리일 때만 하이픈을 넣습니다.
+그 외 길이에서는 하이픈을 추가하지 않고 숫자만 남긴 값을 그대로 반환합니다.
+
+## Hooks
+
+### useJapanPostalCode
+
+우편번호로 주소를 조회합니다. `3~7자리` 숫자 입력을 받아 `3~6자리`일 때는
+prefix 검색으로 동작합니다.
+
+```tsx
+const { loading, data, error, search, reset } = useJapanPostalCode({
+  dataSource,
+});
+```
+
+### useJapanAddressSearch
+
+자유 형식 키워드로 주소를 검색하며 `debounceMs`를 지원합니다.
+
+```tsx
+const { loading, data, error, search, reset } = useJapanAddressSearch({
+  dataSource,
+  debounceMs: 300,
+});
+```
+
+이 훅은 빈 검색어에 대해 여전히 클라이언트 선제 검증을 수행하고, 요청을 보내기
+전에 `invalid_query`를 반환합니다. 이 검증은 UX 보조 장치이며 서버 검증이나
+서버 계약 처리를 대체하지 않습니다.
+
+### useJapanAddress
+
+우편번호 조회와 키워드 검색을 하나의 훅으로 합칩니다.
+
+```tsx
+const { loading, data, error, searchByPostalCode, searchByKeyword, reset } =
+  useJapanAddress({ dataSource, debounceMs: 300 });
+```
+
+모든 훅은 런타임에서 `dataSource`가 필요합니다.
+
+훅의 public API는 계속 문자열 기반입니다.
+
+- `useJapanPostalCode().search(value: string)`
+- `useJapanAddressSearch().search(query: string)`
+- `useJapanAddress().searchByPostalCode(value: string)`
+- `useJapanAddress().searchByKeyword(query: string)`
+
+대신 훅 내부에서 `dataSource` 호출 전에 request object를 조립합니다.
+
+- 우편번호 조회: `{ value, pageNumber: 0, rowsPerPage: 100 }`
+- 주소 검색: `{ freeword, pageNumber: 0, rowsPerPage: 100 }`
+
+`includeCityDetails`, `includePrefectureDetails` 같은 optional flag는
+기본적으로 넣지 않으며, 필요하면 사용자 data source 구현에서 직접
+지정하면 됩니다.
+
+## 에러 처리 메모
+
+`JapanAddressDataSource`의 두 메서드는 모두 `Page<JapanAddress>`를 직접
+반환해야 합니다. 훅은 그 page payload를 그대로 유지하므로
+`data.elements`, `data.totalElements`, `data.pageNumber`,
+`data.rowsPerPage`를 바로 읽을 수 있습니다.
+
+두 메서드는 선택적인 두 번째 인자도 받을 수 있습니다.
+
+```ts
+type JapanAddressRequestOptions = {
+  signal?: AbortSignal;
+};
+```
+
+훅은 superseded 요청, `reset()`, unmount 정리 상황에서 이전 요청을 취소할 수
+있도록 `signal`을 전달합니다. 백엔드 레이어가 abort를 지원하면 그대로 활용할 수
+있습니다.
+
+권장 에러 코드 매핑:
+
+| 상황 | 권장 코드 |
+| --- | --- |
+| 잘못된 우편번호 입력 | `invalid_postal_code` |
+| 훅 선제 검증 단계의 빈 주소 검색어 | `invalid_query` |
+| 네트워크 실패 | `network_error` |
+| 요청 중단 / 타임아웃 | `timeout` |
+| miss를 오류로 표면화하는 백엔드에서의 검색 결과 없음 | `not_found` |
+| 성공 응답 shape 이상 | `bad_response` |
+| 그 외 백엔드 오류 | `data_source_error` |
+
+이 저장소의 참고 demo 흐름에서는 예시 `dataSource`가 실패 요청을 오직 HTTP
+status code로만 분류합니다. 현재 beta와 정렬된 흐름에서는 빈 `addresszip`
+요청과 우편번호 miss가 모두 `200 + empty page`로 올 수 있고, 이런 경우는 정상
+성공 page로 유지합니다. 그 외 `400` 응답은 `invalid_query`로 매핑할 수 있고,
+miss를 오류로 노출하는 백엔드에서는 `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 컴포넌트는 클라이언트 컴포넌트에서
+사용하는 것이 안전합니다.