@cp949/japanpost-react 1.0.3 → 1.0.4

package/dist/client.d.ts

@@ -1 +1,296 @@
-export * from "./index";
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode, ComponentPropsWithoutRef } from 'react';
+
+/**
+ * `japanpost-react`의 공개 계약과 내부 정규화 계약을 한 곳에 모아 둔 타입 모음이다.
+ * 훅, 입력 컴포넌트, data source, minimal-api 연동 예제가 모두 이 정의를 기준으로 맞물리므로
+ * 필드 의미를 바꿀 때는 런타임 동작뿐 아니라 외부 사용자의 기대 계약도 함께 고려해야 한다.
+ */
+/**
+ * 일본우정 API에서 반환되는 원본 주소 레코드 형태.
+ * 공개 API 표면에는 직접 노출하지 않고 내부에서만 사용한다.
+ */
+type JapanPostApiAddressRecord = {
+    zip_code?: string | number | null;
+    pref_code?: string | number | null;
+    pref_name?: string | null;
+    pref_kana?: string | null;
+    city_name?: string | null;
+    city_kana?: string | null;
+    town_name?: string | null;
+    town_kana?: string | null;
+    block_name?: string | null;
+    other_name?: string | null;
+    address?: string | null;
+};
+/**
+ * 우편번호로 주소를 검색할 때(searchcode) API 응답 형태.
+ */
+type JapanPostSearchCodeResponse = {
+    addresses?: JapanPostApiAddressRecord[] | null;
+    message?: string | null;
+    status?: number;
+};
+/**
+ * 주소 키워드로 검색할 때(addresszip) API 응답 형태.
+ */
+type JapanPostAddressZipResponse = {
+    addresses?: JapanPostApiAddressRecord[] | null;
+    message?: string | null;
+    status?: number;
+};
+type JapanPostApiResponse = JapanPostSearchCodeResponse | JapanPostAddressZipResponse;
+/**
+ * minimal-api가 그대로 받는 공개 searchcode 요청 타입이다.
+ * pageNumber/rowsPerPage를 노출하는 이유는 라이브러리와 API 예제가 같은 pager 의미 체계를 공유하기 위해서다.
+ */
+type JapanPostSearchcodeRequest = {
+    postalCode: string;
+    pageNumber: number;
+    rowsPerPage: number;
+    includeParenthesesTown?: boolean | null;
+};
+/**
+ * useJapanPostalCode의 공개 검색 입력 타입.
+ * 문자열 입력은 기존 호환성을 유지하고, 객체 입력은 pager 옵션을 함께 전달할 수 있게 한다.
+ */
+type JapanPostalCodeSearchInput = string | {
+    postalCode: string;
+    pageNumber?: number;
+    rowsPerPage?: number;
+    includeParenthesesTown?: boolean | null;
+};
+/**
+ * useJapanAddressSearch의 공개 검색 입력 타입.
+ * 문자열 입력은 키워드 검색 호환성을 유지하고, 객체 입력은 자유 검색과 구조화 검색 필드를 함께 전달할 수 있게 한다.
+ */
+type JapanAddressSearchInput = string | (Omit<JapanPostAddresszipRequest, "pageNumber" | "rowsPerPage"> & {
+    pageNumber?: number;
+    rowsPerPage?: number;
+});
+/**
+ * minimal-api가 그대로 받는 공개 addresszip 요청 타입이다.
+ * 자유 검색(addressQuery)뿐 아니라 구조화 검색 필드도 함께 열어 두어
+ * 상위 UI가 필요한 만큼만 업스트림 검색 축을 선택적으로 노출할 수 있게 한다.
+ */
+type JapanPostAddresszipRequest = {
+    addressQuery?: string | null;
+    prefCode?: string | null;
+    prefName?: string | null;
+    prefKana?: string | null;
+    prefRoma?: string | null;
+    cityCode?: string | null;
+    cityName?: string | null;
+    cityKana?: string | null;
+    cityRoma?: string | null;
+    townName?: string | null;
+    townKana?: string | null;
+    townRoma?: string | null;
+    pageNumber: number;
+    rowsPerPage: number;
+    includeCityDetails?: boolean | null;
+    includePrefectureDetails?: boolean | null;
+};
+/**
+ * API 응답을 정규화한 후의 중간 주소 레코드 형태.
+ * 내부 data source 처리 후 공개 JapanAddress 타입으로 변환되기 전에 사용된다.
+ */
+type NormalizedJapanAddressRecord = {
+    postalCode: string;
+    prefecture: string;
+    prefectureKana?: string;
+    city: string;
+    cityKana?: string;
+    town: string;
+    townKana?: string;
+    detail?: string;
+};
+/**
+ * 라이브러리 공개 주소 타입. 훅과 클라이언트가 외부로 반환하는 최종 형태.
+ * `address`는 표시 편의를 위한 결합 문자열이고, 나머지 필드는 후처리/재조합이 가능한 구조화 값이다.
+ */
+type JapanAddress = {
+    postalCode: string;
+    prefecture: string;
+    prefectureKana?: string;
+    city: string;
+    cityKana?: string;
+    town: string;
+    townKana?: string;
+    address: string;
+    provider: "japan-post";
+};
+/**
+ * minimal-api와 라이브러리가 공통으로 사용하는 pager 응답 계약이다.
+ * 페이지 기반 UI가 아니더라도 total/page 정보를 유지해 "결과 없음"과 "일부만 조회됨"을 구분할 수 있다.
+ */
+type Page<T> = {
+    elements: T[];
+    totalElements: number;
+    pageNumber: number;
+    rowsPerPage: number;
+};
+/**
+ * 우편번호 조회 결과.
+ * 단일 주소만 기대하는 소비자도 있을 수 있지만, 업스트림 계약이 목록 + 페이징이므로 그대로 보존한다.
+ */
+type JapanPostalCodeLookupResult = Page<JapanAddress>;
+/**
+ * 키워드 주소 검색 결과.
+ * postal code 조회와 동일한 pager 형태를 사용해 두 검색 모드를 같은 UI로 렌더링할 수 있게 한다.
+ */
+type JapanAddressSearchResult = Page<JapanAddress>;
+/**
+ * 라이브러리 전용 오류 코드 목록.
+ * 소비자는 message 문자열보다 code를 기준으로 UX를 분기하는 것이 안전하다.
+ */
+type JapanAddressErrorCode = "invalid_postal_code" | "invalid_query" | "network_error" | "timeout" | "not_found" | "bad_response" | "data_source_error";
+/**
+ * 라이브러리 전용 에러 타입. 훅과 data source 전반에서 일관되게 사용된다.
+ * 브라우저/서버/사용자 입력 오류를 모두 같은 형태로 감싸 public contract를 단순화한다.
+ */
+type JapanAddressError = Error & {
+    name: "JapanAddressError";
+    code: JapanAddressErrorCode;
+    cause?: unknown;
+    status?: number;
+};
+/**
+ * data source 요청에 전달할 선택 옵션.
+ * 현재는 AbortSignal만 쓰지만, 추후 timeout/metadata가 필요해져도 호출부 시그니처를 크게 흔들지 않기 위한 확장 지점이다.
+ */
+type JapanAddressRequestOptions = {
+    signal?: AbortSignal;
+};
+/**
+ * 주소 데이터를 제공하는 data source 인터페이스.
+ * 커스텀 구현체로 교체할 수 있도록 추상화되어 있다.
+ * 즉, 훅은 fetch 구현을 모르고 pager 계약과 에러 계약만 신뢰한다.
+ */
+type JapanAddressDataSource = {
+    lookupPostalCode: (request: JapanPostSearchcodeRequest, options?: JapanAddressRequestOptions) => Promise<Page<JapanAddress>>;
+    searchAddress: (request: JapanPostAddresszipRequest, options?: JapanAddressRequestOptions) => Promise<Page<JapanAddress>>;
+};
+/**
+ * useJapanPostalCode 훅 옵션.
+ * data source 주입 방식으로 브라우저 직접 호출, BFF, mock을 모두 같은 훅으로 다룬다.
+ */
+type UseJapanPostalCodeOptions = {
+    dataSource: JapanAddressDataSource;
+};
+/**
+ * useJapanAddressSearch 훅 옵션.
+ * debounce는 UI 입력 빈도를 제어하기 위한 것이며 data source 계약을 바꾸지 않는다.
+ */
+type UseJapanAddressSearchOptions = {
+    dataSource: JapanAddressDataSource;
+    debounceMs?: number;
+};
+/**
+ * useJapanAddress 훅 옵션.
+ * 통합 훅도 내부적으로는 두 검색 훅을 조합하므로 필요한 옵션만 얇게 위임한다.
+ */
+type UseJapanAddressOptions = {
+    dataSource: JapanAddressDataSource;
+    debounceMs?: number;
+};
+/**
+ * 비동기 데이터 로딩 상태를 표현하는 제네릭 타입.
+ * 모든 훅이 같은 상태 모양을 공유하면 소비자 컴포넌트가 검색 종류와 무관하게 공통 렌더링 로직을 가질 수 있다.
+ */
+type UseAsyncState<T> = {
+    loading: boolean;
+    data: T | null;
+    error: JapanAddressError | null;
+};
+/**
+ * useJapanPostalCode 훅의 반환 타입.
+ * search는 실패나 취소 시 null을 반환해 UI가 try/catch 없이도 분기할 수 있게 한다.
+ */
+type UseJapanPostalCodeResult = UseAsyncState<JapanPostalCodeLookupResult> & {
+    cancel: () => void;
+    reset: () => void;
+    search: (input: JapanPostalCodeSearchInput) => Promise<JapanPostalCodeLookupResult | null>;
+};
+/**
+ * useJapanAddressSearch 훅의 반환 타입.
+ * debounce 취소와 오류 모두 Promise 결과 관점에서는 null로 귀결될 수 있으므로 호출부는 state와 함께 해석해야 한다.
+ */
+type UseJapanAddressSearchResult = UseAsyncState<JapanAddressSearchResult> & {
+    cancel: () => void;
+    reset: () => void;
+    search: (input: JapanAddressSearchInput) => Promise<JapanAddressSearchResult | null>;
+};
+/**
+ * useJapanAddress 훅의 반환 타입.
+ * data/error는 "현재 활성 검색 모드" 기준 값이며, 두 내부 훅의 상태 전체를 그대로 노출하지는 않는다.
+ */
+type UseJapanAddressResult = UseAsyncState<Page<JapanAddress>> & {
+    reset: () => void;
+    searchByPostalCode: (input: JapanPostalCodeSearchInput) => Promise<JapanPostalCodeLookupResult | null>;
+    searchByAddressQuery: (input: JapanAddressSearchInput) => Promise<JapanAddressSearchResult | null>;
+};
+/**
+ * 검색 입력 컴포넌트들이 공유하는 공통 props.
+ * 제어/비제어 모드를 모두 지원해 폼 라이브러리와 단순 데모 예제를 같은 컴포넌트로 소화한다.
+ */
+type BaseTextSearchInputProps = {
+    defaultValue?: string;
+    value?: string;
+    disabled?: boolean;
+    label?: ReactNode;
+    buttonLabel?: ReactNode;
+    inputProps?: Omit<ComponentPropsWithoutRef<"input">, "defaultValue" | "disabled" | "onChange" | "value">;
+    buttonProps?: Omit<ComponentPropsWithoutRef<"button">, "children" | "disabled" | "onClick" | "type">;
+};
+/**
+ * PostalCodeInput 컴포넌트 props.
+ * onSearch는 표시 문자열이 아니라 정규화된 우편번호를 받는다는 점이 핵심 계약이다.
+ */
+type PostalCodeInputProps = BaseTextSearchInputProps & {
+    onChange?: (postalCode: string) => void;
+    onSearch: (postalCode: string) => void;
+};
+/**
+ * AddressSearchInput 컴포넌트 props.
+ * onSearch에는 trim 처리된 검색어가 전달되어 공백만 다른 입력이 별도 쿼리로 취급되지 않게 한다.
+ */
+type AddressSearchInputProps = BaseTextSearchInputProps & {
+    onChange?: (query: string) => void;
+    onSearch: (query: string) => void;
+};
+
+/**
+ * 스타일 의존성이 없는 최소한의 주소 키워드 검색 입력 컴포넌트.
+ * 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 };