@cp949/japanpost-react 1.0.2 → 1.0.4

package/README.ko.md

@@ -18,6 +18,28 @@ pnpm add @cp949/japanpost-react
 
 - 지원 React 버전: React 18, React 19
 
+이 패키지는 ESM으로 배포됩니다. 서버 유틸리티와 공용 타입은
+`@cp949/japanpost-react`에서 가져오고, Next.js App Router에서 훅이나
+headless 입력 컴포넌트는 `@cp949/japanpost-react/client`를 사용하세요.
+`require("@cp949/japanpost-react")`,
+`require("@cp949/japanpost-react/client")`는 지원되지 않으며, CommonJS
+소비자는 `const pkg = await import("@cp949/japanpost-react");` 같은 ESM
+interop을 사용해야 합니다.
+
+## Next.js
+
+Next.js App Router에서 훅이나 headless 입력 컴포넌트를 쓸 때는
+클라이언트 컴포넌트 안에서 `@cp949/japanpost-react/client` 경로를
+사용하는 것을 권장합니다. 유틸리티 함수와 공용 타입은 루트 엔트리에서
+가져오면 됩니다.
+
+```tsx
+"use client";
+
+import { PostalCodeInput, useJapanPostalCode } from "@cp949/japanpost-react/client";
+import { normalizeJapanPostalCode, type JapanAddressDataSource } from "@cp949/japanpost-react";
+```
+
 ## 빠른 시작
 
 ```tsx
@@ -157,6 +179,9 @@ export function PostalForm() {
 성공할 수 있고, `404 -> not_found`는 miss를 오류로 노출하는 백엔드에서만
 선택적으로 쓰면 됩니다.
 
+Next.js에서도 `dataSource`는 자체 서버 API를 바라보도록 두고, Japan Post
+업스트림 자격 증명과 토큰 교환은 브라우저가 아니라 서버에서 처리하세요.
+
 ## Exports
 
 - `normalizeJapanPostalCode`
@@ -345,5 +370,6 @@ timeout 메시지는 토큰 발급 단계와 실제 조회 단계 중 어느 쪽
 ## SSR
 
 `dataSource` 구현에서는 서버 측 API를 사용하고, 토큰 교환과 업스트림 서명은
-서버에서만 처리하세요. React 훅과 UI 컴포넌트는 클라이언트 컴포넌트에서
+서버에서만 처리하세요. Next.js App Router에서는 React 훅과 UI 컴포넌트를
+`@cp949/japanpost-react/client`에서 import해 클라이언트 컴포넌트에서
 사용하는 것이 안전합니다.

package/README.md

@@ -21,6 +21,26 @@ pnpm add @cp949/japanpost-react
   `packages/japanpost-react`
 - Demo app in this repository: `apps/demo`
 
+This package is published as ESM. Keep server utilities and shared types on
+`@cp949/japanpost-react`, and import hooks or headless input components for the
+Next.js App Router from `@cp949/japanpost-react/client`. CommonJS consumers
+must use ESM interop. `require("@cp949/japanpost-react")` and
+`require("@cp949/japanpost-react/client")` are not supported. In CommonJS, use
+ESM interop such as `const pkg = await import("@cp949/japanpost-react");`.
+
+## Next.js
+
+When you use hooks or headless input components in the Next.js App Router,
+import them from `@cp949/japanpost-react/client` inside a Client Component.
+Keep utility functions and shared types on the root entry.
+
+```tsx
+"use client";
+
+import { PostalCodeInput, useJapanPostalCode } from "@cp949/japanpost-react/client";
+import { normalizeJapanPostalCode, type JapanAddressDataSource } from "@cp949/japanpost-react";
+```
+
 ## What The Package Provides
 
 - Hooks for postal-code lookup and address search:
@@ -163,6 +183,10 @@ The example paths above match this repository's reference backend. In your own
 app, the backend routes can be different as long as your `dataSource`
 implementation returns the same public types.
 
+In Next.js, keep the `dataSource` implementation pointed at your own server-side
+API routes. Do not expose Japan Post credentials or token exchange logic to the
+browser.
+
 ## Core Contract
 
 `Page<T>` is the result shape shared by the hooks and the reference backend:

package/dist/{src/core/types.d.ts → client.d.ts}

@@ -1,4 +1,6 @@
-import { ComponentPropsWithoutRef, ReactNode } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode, ComponentPropsWithoutRef } from 'react';
+
 /**
  * `japanpost-react`의 공개 계약과 내부 정규화 계약을 한 곳에 모아 둔 타입 모음이다.
  * 훅, 입력 컴포넌트, data source, minimal-api 연동 예제가 모두 이 정의를 기준으로 맞물리므로
@@ -8,7 +10,7 @@ import { ComponentPropsWithoutRef, ReactNode } from 'react';
  * 일본우정 API에서 반환되는 원본 주소 레코드 형태.
  * 공개 API 표면에는 직접 노출하지 않고 내부에서만 사용한다.
  */
-export type JapanPostApiAddressRecord = {
+type JapanPostApiAddressRecord = {
     zip_code?: string | number | null;
     pref_code?: string | number | null;
     pref_name?: string | null;
@@ -24,7 +26,7 @@ export type JapanPostApiAddressRecord = {
 /**
  * 우편번호로 주소를 검색할 때(searchcode) API 응답 형태.
  */
-export type JapanPostSearchCodeResponse = {
+type JapanPostSearchCodeResponse = {
     addresses?: JapanPostApiAddressRecord[] | null;
     message?: string | null;
     status?: number;
@@ -32,17 +34,17 @@ export type JapanPostSearchCodeResponse = {
 /**
  * 주소 키워드로 검색할 때(addresszip) API 응답 형태.
  */
-export type JapanPostAddressZipResponse = {
+type JapanPostAddressZipResponse = {
     addresses?: JapanPostApiAddressRecord[] | null;
     message?: string | null;
     status?: number;
 };
-export type JapanPostApiResponse = JapanPostSearchCodeResponse | JapanPostAddressZipResponse;
+type JapanPostApiResponse = JapanPostSearchCodeResponse | JapanPostAddressZipResponse;
 /**
  * minimal-api가 그대로 받는 공개 searchcode 요청 타입이다.
  * pageNumber/rowsPerPage를 노출하는 이유는 라이브러리와 API 예제가 같은 pager 의미 체계를 공유하기 위해서다.
  */
-export type JapanPostSearchcodeRequest = {
+type JapanPostSearchcodeRequest = {
     postalCode: string;
     pageNumber: number;
     rowsPerPage: number;
@@ -52,7 +54,7 @@ export type JapanPostSearchcodeRequest = {
  * useJapanPostalCode의 공개 검색 입력 타입.
  * 문자열 입력은 기존 호환성을 유지하고, 객체 입력은 pager 옵션을 함께 전달할 수 있게 한다.
  */
-export type JapanPostalCodeSearchInput = string | {
+type JapanPostalCodeSearchInput = string | {
     postalCode: string;
     pageNumber?: number;
     rowsPerPage?: number;
@@ -62,7 +64,7 @@ export type JapanPostalCodeSearchInput = string | {
  * useJapanAddressSearch의 공개 검색 입력 타입.
  * 문자열 입력은 키워드 검색 호환성을 유지하고, 객체 입력은 자유 검색과 구조화 검색 필드를 함께 전달할 수 있게 한다.
  */
-export type JapanAddressSearchInput = string | (Omit<JapanPostAddresszipRequest, "pageNumber" | "rowsPerPage"> & {
+type JapanAddressSearchInput = string | (Omit<JapanPostAddresszipRequest, "pageNumber" | "rowsPerPage"> & {
     pageNumber?: number;
     rowsPerPage?: number;
 });
@@ -71,7 +73,7 @@ export type JapanAddressSearchInput = string | (Omit<JapanPostAddresszipRequest,
  * 자유 검색(addressQuery)뿐 아니라 구조화 검색 필드도 함께 열어 두어
  * 상위 UI가 필요한 만큼만 업스트림 검색 축을 선택적으로 노출할 수 있게 한다.
  */
-export type JapanPostAddresszipRequest = {
+type JapanPostAddresszipRequest = {
     addressQuery?: string | null;
     prefCode?: string | null;
     prefName?: string | null;
@@ -93,7 +95,7 @@ export type JapanPostAddresszipRequest = {
  * API 응답을 정규화한 후의 중간 주소 레코드 형태.
  * 내부 data source 처리 후 공개 JapanAddress 타입으로 변환되기 전에 사용된다.
  */
-export type NormalizedJapanAddressRecord = {
+type NormalizedJapanAddressRecord = {
     postalCode: string;
     prefecture: string;
     prefectureKana?: string;
@@ -107,7 +109,7 @@ export type NormalizedJapanAddressRecord = {
  * 라이브러리 공개 주소 타입. 훅과 클라이언트가 외부로 반환하는 최종 형태.
  * `address`는 표시 편의를 위한 결합 문자열이고, 나머지 필드는 후처리/재조합이 가능한 구조화 값이다.
  */
-export type JapanAddress = {
+type JapanAddress = {
     postalCode: string;
     prefecture: string;
     prefectureKana?: string;
@@ -122,7 +124,7 @@ export type JapanAddress = {
  * minimal-api와 라이브러리가 공통으로 사용하는 pager 응답 계약이다.
  * 페이지 기반 UI가 아니더라도 total/page 정보를 유지해 "결과 없음"과 "일부만 조회됨"을 구분할 수 있다.
  */
-export type Page<T> = {
+type Page<T> = {
     elements: T[];
     totalElements: number;
     pageNumber: number;
@@ -132,22 +134,22 @@ export type Page<T> = {
  * 우편번호 조회 결과.
  * 단일 주소만 기대하는 소비자도 있을 수 있지만, 업스트림 계약이 목록 + 페이징이므로 그대로 보존한다.
  */
-export type JapanPostalCodeLookupResult = Page<JapanAddress>;
+type JapanPostalCodeLookupResult = Page<JapanAddress>;
 /**
  * 키워드 주소 검색 결과.
  * postal code 조회와 동일한 pager 형태를 사용해 두 검색 모드를 같은 UI로 렌더링할 수 있게 한다.
  */
-export type JapanAddressSearchResult = Page<JapanAddress>;
+type JapanAddressSearchResult = Page<JapanAddress>;
 /**
  * 라이브러리 전용 오류 코드 목록.
  * 소비자는 message 문자열보다 code를 기준으로 UX를 분기하는 것이 안전하다.
  */
-export type JapanAddressErrorCode = "invalid_postal_code" | "invalid_query" | "network_error" | "timeout" | "not_found" | "bad_response" | "data_source_error";
+type JapanAddressErrorCode = "invalid_postal_code" | "invalid_query" | "network_error" | "timeout" | "not_found" | "bad_response" | "data_source_error";
 /**
  * 라이브러리 전용 에러 타입. 훅과 data source 전반에서 일관되게 사용된다.
  * 브라우저/서버/사용자 입력 오류를 모두 같은 형태로 감싸 public contract를 단순화한다.
  */
-export type JapanAddressError = Error & {
+type JapanAddressError = Error & {
     name: "JapanAddressError";
     code: JapanAddressErrorCode;
     cause?: unknown;
@@ -157,7 +159,7 @@ export type JapanAddressError = Error & {
  * data source 요청에 전달할 선택 옵션.
  * 현재는 AbortSignal만 쓰지만, 추후 timeout/metadata가 필요해져도 호출부 시그니처를 크게 흔들지 않기 위한 확장 지점이다.
  */
-export type JapanAddressRequestOptions = {
+type JapanAddressRequestOptions = {
     signal?: AbortSignal;
 };
 /**
@@ -165,7 +167,7 @@ export type JapanAddressRequestOptions = {
  * 커스텀 구현체로 교체할 수 있도록 추상화되어 있다.
  * 즉, 훅은 fetch 구현을 모르고 pager 계약과 에러 계약만 신뢰한다.
  */
-export type JapanAddressDataSource = {
+type JapanAddressDataSource = {
     lookupPostalCode: (request: JapanPostSearchcodeRequest, options?: JapanAddressRequestOptions) => Promise<Page<JapanAddress>>;
     searchAddress: (request: JapanPostAddresszipRequest, options?: JapanAddressRequestOptions) => Promise<Page<JapanAddress>>;
 };
@@ -173,14 +175,14 @@ export type JapanAddressDataSource = {
  * useJapanPostalCode 훅 옵션.
  * data source 주입 방식으로 브라우저 직접 호출, BFF, mock을 모두 같은 훅으로 다룬다.
  */
-export type UseJapanPostalCodeOptions = {
+type UseJapanPostalCodeOptions = {
     dataSource: JapanAddressDataSource;
 };
 /**
  * useJapanAddressSearch 훅 옵션.
  * debounce는 UI 입력 빈도를 제어하기 위한 것이며 data source 계약을 바꾸지 않는다.
  */
-export type UseJapanAddressSearchOptions = {
+type UseJapanAddressSearchOptions = {
     dataSource: JapanAddressDataSource;
     debounceMs?: number;
 };
@@ -188,7 +190,7 @@ export type UseJapanAddressSearchOptions = {
  * useJapanAddress 훅 옵션.
  * 통합 훅도 내부적으로는 두 검색 훅을 조합하므로 필요한 옵션만 얇게 위임한다.
  */
-export type UseJapanAddressOptions = {
+type UseJapanAddressOptions = {
     dataSource: JapanAddressDataSource;
     debounceMs?: number;
 };
@@ -196,7 +198,7 @@ export type UseJapanAddressOptions = {
  * 비동기 데이터 로딩 상태를 표현하는 제네릭 타입.
  * 모든 훅이 같은 상태 모양을 공유하면 소비자 컴포넌트가 검색 종류와 무관하게 공통 렌더링 로직을 가질 수 있다.
  */
-export type UseAsyncState<T> = {
+type UseAsyncState<T> = {
     loading: boolean;
     data: T | null;
     error: JapanAddressError | null;
@@ -205,7 +207,7 @@ export type UseAsyncState<T> = {
  * useJapanPostalCode 훅의 반환 타입.
  * search는 실패나 취소 시 null을 반환해 UI가 try/catch 없이도 분기할 수 있게 한다.
  */
-export type UseJapanPostalCodeResult = UseAsyncState<JapanPostalCodeLookupResult> & {
+type UseJapanPostalCodeResult = UseAsyncState<JapanPostalCodeLookupResult> & {
     cancel: () => void;
     reset: () => void;
     search: (input: JapanPostalCodeSearchInput) => Promise<JapanPostalCodeLookupResult | null>;
@@ -214,7 +216,7 @@ export type UseJapanPostalCodeResult = UseAsyncState<JapanPostalCodeLookupResult
  * useJapanAddressSearch 훅의 반환 타입.
  * debounce 취소와 오류 모두 Promise 결과 관점에서는 null로 귀결될 수 있으므로 호출부는 state와 함께 해석해야 한다.
  */
-export type UseJapanAddressSearchResult = UseAsyncState<JapanAddressSearchResult> & {
+type UseJapanAddressSearchResult = UseAsyncState<JapanAddressSearchResult> & {
     cancel: () => void;
     reset: () => void;
     search: (input: JapanAddressSearchInput) => Promise<JapanAddressSearchResult | null>;
@@ -223,7 +225,7 @@ export type UseJapanAddressSearchResult = UseAsyncState<JapanAddressSearchResult
  * useJapanAddress 훅의 반환 타입.
  * data/error는 "현재 활성 검색 모드" 기준 값이며, 두 내부 훅의 상태 전체를 그대로 노출하지는 않는다.
  */
-export type UseJapanAddressResult = UseAsyncState<Page<JapanAddress>> & {
+type UseJapanAddressResult = UseAsyncState<Page<JapanAddress>> & {
     reset: () => void;
     searchByPostalCode: (input: JapanPostalCodeSearchInput) => Promise<JapanPostalCodeLookupResult | null>;
     searchByAddressQuery: (input: JapanAddressSearchInput) => Promise<JapanAddressSearchResult | null>;
@@ -245,7 +247,7 @@ type BaseTextSearchInputProps = {
  * PostalCodeInput 컴포넌트 props.
  * onSearch는 표시 문자열이 아니라 정규화된 우편번호를 받는다는 점이 핵심 계약이다.
  */
-export type PostalCodeInputProps = BaseTextSearchInputProps & {
+type PostalCodeInputProps = BaseTextSearchInputProps & {
     onChange?: (postalCode: string) => void;
     onSearch: (postalCode: string) => void;
 };
@@ -253,9 +255,42 @@ export type PostalCodeInputProps = BaseTextSearchInputProps & {
  * AddressSearchInput 컴포넌트 props.
  * onSearch에는 trim 처리된 검색어가 전달되어 공백만 다른 입력이 별도 쿼리로 취급되지 않게 한다.
  */
-export type AddressSearchInputProps = BaseTextSearchInputProps & {
+type AddressSearchInputProps = BaseTextSearchInputProps & {
     onChange?: (query: string) => void;
     onSearch: (query: string) => void;
 };
-export {};
-//# sourceMappingURL=types.d.ts.map
+
+/**
+ * 스타일 의존성이 없는 최소한의 주소 키워드 검색 입력 컴포넌트.
+ * value를 전달하면 제어 모드, 전달하지 않으면 비제어 모드로 동작한다.
+ * 검색 시 trim 처리를 내부에서 수행해 공백만 다른 입력이 별도 쿼리로 번지지 않게 한다.
+ */
+declare function AddressSearchInput({ defaultValue, value, disabled, label, buttonLabel, inputProps, buttonProps, onChange, onSearch, }: AddressSearchInputProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * 스타일 의존성이 없는 최소한의 우편번호 입력 컴포넌트.
+ * value를 전달하면 제어 모드, 전달하지 않으면 비제어 모드로 동작한다.
+ * 제출 시에는 표시 형식이 아니라 정규화된 숫자 문자열을 콜백에 넘기는 것이 핵심 계약이다.
+ */
+declare function PostalCodeInput({ defaultValue, value, disabled, label, buttonLabel, inputProps, buttonProps, onChange, onSearch, }: PostalCodeInputProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * 우편번호 조회와 키워드 주소 검색을 하나의 인터페이스로 제공하는 통합 훅.
+ * 두 검색 모드가 공유하는 data source를 내부에서 재사용하고,
+ * 마지막으로 실행된 검색 종류만 외부에 노출해 두 결과가 섞이지 않도록 한다.
+ */
+declare function useJapanAddress(options: UseJapanAddressOptions): UseJapanAddressResult;
+
+/**
+ * 자유 형식 키워드로 일본 주소를 검색하는 훅.
+ * 디바운스를 지원하며 loading / data / error 상태와 search / reset 함수를 제공한다.
+ */
+declare function useJapanAddressSearch(options: UseJapanAddressSearchOptions): UseJapanAddressSearchResult;
+
+/**
+ * 일본 우편번호로 주소를 조회하는 훅.
+ * loading / data / error 상태와 search / reset 함수를 제공한다.
+ */
+declare function useJapanPostalCode(options: UseJapanPostalCodeOptions): UseJapanPostalCodeResult;
+
+export { AddressSearchInput, type AddressSearchInputProps, type JapanAddress, type JapanAddressDataSource, type JapanAddressError, type JapanAddressErrorCode, type JapanAddressRequestOptions, type JapanAddressSearchInput, type JapanAddressSearchResult, type JapanPostAddressZipResponse, type JapanPostAddresszipRequest, type JapanPostApiAddressRecord, type JapanPostApiResponse, type JapanPostSearchCodeResponse, type JapanPostSearchcodeRequest, type JapanPostalCodeLookupResult, type JapanPostalCodeSearchInput, type NormalizedJapanAddressRecord, type Page, PostalCodeInput, type PostalCodeInputProps, type UseAsyncState, type UseJapanAddressOptions, type UseJapanAddressResult, type UseJapanAddressSearchOptions, type UseJapanAddressSearchResult, type UseJapanPostalCodeOptions, type UseJapanPostalCodeResult, useJapanAddress, useJapanAddressSearch, useJapanPostalCode };