@cp949/japanpost-react 1.0.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 cp949
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,500 @@
+<!-- This file is generated by `pnpm readme:package`. Edit docs/README.en.md and docs/README.ko.md instead. -->
+
+# @cp949/japanpost-react
+
+[English](#english) | [한국어](#한국어)
+
+---
+
+## English
+
+React + TypeScript hooks and headless inputs for Japan postal-code and address
+lookup.
+
+This package guide covers the published library. Repository-level demo scripts
+such as `pnpm demo:full` currently target Linux/WSL-style shell environments
+and are documented in the root README.
+
+## Install
+
+```bash
+pnpm add @cp949/japanpost-react
+```
+
+- Supported React versions: React 18 and React 19
+
+## Quick Start
+
+```tsx
+import { useJapanPostalCode } from "@cp949/japanpost-react";
+import type { JapanAddressDataSource } 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.
+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")}>Search</button>
+      {loading && <p>Loading...</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`
+- Public types including `JapanAddress` and `JapanAddressDataSource`
+- Request options type: `JapanAddressRequestOptions`
+
+## Utility Notes
+
+`formatJapanPostalCode()` inserts a hyphen only when the normalized value is
+exactly 7 digits. For any other length, it returns the normalized digits
+without inserting a hyphen.
+
+## Hooks
+
+### useJapanPostalCode
+
+Looks up addresses by postal code.
+
+```tsx
+const { loading, data, error, search, reset } = useJapanPostalCode({
+  dataSource,
+});
+```
+
+### useJapanAddressSearch
+
+Searches addresses by free-form keyword and supports debouncing.
+
+```tsx
+const { loading, data, error, search, reset } = useJapanAddressSearch({
+  dataSource,
+  debounceMs: 300,
+});
+```
+
+### useJapanAddress
+
+Combines postal-code lookup and keyword search into one hook.
+
+```tsx
+const { loading, data, error, searchByPostalCode, searchByKeyword, reset } =
+  useJapanAddress({ dataSource, debounceMs: 300 });
+```
+
+All hooks require `dataSource` at runtime.
+
+## Error Handling Notes
+
+`JapanAddressDataSource` should return `JapanAddress[]` directly from both
+methods. The hooks wrap those arrays into lookup/search result objects.
+
+Both methods may also receive an optional second argument:
+
+```ts
+type JapanAddressRequestOptions = {
+  signal?: AbortSignal;
+};
+```
+
+Hooks pass `signal` so your data source can cancel superseded requests,
+`reset()` calls, and unmount cleanup when your backend layer supports aborts.
+
+Recommended error-code mapping:
+
+| Situation | Recommended code |
+| --- | --- |
+| Invalid postal code input | `invalid_postal_code` |
+| Blank keyword input | `invalid_query` |
+| Network failure | `network_error` |
+| Request aborted / timeout | `timeout` |
+| No matching addresses | `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`.
+
+## Headless Components
+
+`PostalCodeInput` and `AddressSearchInput` provide behavior and DOM structure
+without bundled styles, so you can plug them into your own design system.
+
+Both components also support native prop passthrough:
+
+- `inputProps`: forwarded to the rendered `<input />`
+- `buttonProps`: forwarded to the rendered `<button />`
+
+Use these for `id`, `name`, `placeholder`, `aria-*`, `autoComplete`,
+`className`, and form integration. `PostalCodeInput` defaults to
+`inputMode="numeric"` unless you override it through `inputProps`.
+
+## Data Source and Server Integration
+
+Use this package with your own backend server. The official Japan Post flow
+uses token-based authentication, so browser apps should not hold upstream
+credentials directly. The supported integration model is a real server-backed
+flow.
+
+This repository includes `apps/minimal-api` as the reference local server. It
+wraps Japan Post API ver 2.0 and is intended for local development and
+integration testing. The demo's `/minimal-api` path is only a development-time
+route to that local server. When the upstream payload includes both structured
+address parts and a free-form `address` string, the reference server keeps the
+display address non-duplicated instead of concatenating both blindly.
+
+Timeout messages can differ depending on whether the token exchange timed out or
+the upstream lookup request timed out. Both cases still map cleanly to the
+`timeout` error code.
+
+## SSR
+
+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

@@ -0,0 +1,7 @@
+import { AddressSearchInputProps } from '../core/types';
+/**
+ * 스타일 의존성이 없는 최소한의 주소 키워드 검색 입력 컴포넌트.
+ * value를 전달하면 제어 모드, 전달하지 않으면 비제어 모드로 동작한다.
+ */
+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

@@ -0,0 +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"}

package/dist/components/PostalCodeInput.d.ts

@@ -0,0 +1,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

@@ -0,0 +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"}

package/dist/core/errors.d.ts

@@ -0,0 +1,10 @@
+import { JapanAddressError, JapanAddressErrorCode } from './types';
+/**
+ * 라이브러리 전용 에러 객체를 생성한다.
+ * name과 code를 일관되게 설정해 catch 블록에서 타입 좁히기가 쉽도록 한다.
+ */
+export declare function createJapanAddressError(code: JapanAddressErrorCode, message: string, options?: {
+    cause?: unknown;
+    status?: number;
+}): JapanAddressError;
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +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"}

package/dist/core/formatters.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 우편번호에서 숫자가 아닌 문자(하이픈 등)를 제거해 순수 숫자 문자열로 만든다.
+ * 예: "123-4567" → "1234567"
+ */
+export declare function normalizeJapanPostalCode(value: string): string;
+/**
+ * 우편번호를 "NNN-NNNN" 형식으로 포맷한다.
+ * 정확히 7자리가 아닐 때는 하이픈 없이 숫자만 반환한다.
+ * 예: "1234567" → "123-4567"
+ */
+export declare function formatJapanPostalCode(value: string): string;
+//# sourceMappingURL=formatters.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"formatters.d.ts","sourceRoot":"","sources":["../../src/core/formatters.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAG9D;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAW3D"}

package/dist/core/normalizers.d.ts

@@ -0,0 +1,7 @@
+import { JapanAddress, NormalizedJapanAddressRecord } from './types';
+/**
+ * 정규화된 내부 주소 레코드를 라이브러리 공개 JapanAddress 형태로 변환한다.
+ * address는 도도부현·시구정촌·동·상세주소를 순서대로 이어붙인 문자열이다.
+ */
+export declare function normalizeJapanPostAddressRecord(record: NormalizedJapanAddressRecord): JapanAddress;
+//# sourceMappingURL=normalizers.d.ts.map

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

@@ -0,0 +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"}