@cp949/japanpost-react 1.0.0 → 1.0.2

package/README.md

@@ -1,19 +1,14 @@
-<!-- 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.
+React hooks, headless input components, and utilities 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.
+This package does not call Japan Post directly. You provide a
+`JapanAddressDataSource` that talks to your own backend API.
 
 ## Install
 
@@ -21,480 +16,315 @@ and are documented in the root README.
 pnpm add @cp949/japanpost-react
 ```
 
-- Supported React versions: React 18 and React 19
+- Peer dependencies: React 18 or React 19
+- Package source in this repository:
+  `packages/japanpost-react`
+- Demo app in this repository: `apps/demo`
+
+## What The Package Provides
+
+- Hooks for postal-code lookup and address search:
+  `useJapanPostalCode`, `useJapanAddressSearch`, `useJapanAddress`
+- Headless form components:
+  `PostalCodeInput`, `AddressSearchInput`
+- Utilities:
+  `normalizeJapanPostalCode`, `formatJapanPostalCode`,
+  `isValidJapanPostalCode`, `normalizeJapanPostAddressRecord`,
+  `createJapanAddressError`
+- Public types for the request, response, error, and data-source contracts
 
 ## Quick Start
 
+The package expects a `JapanAddressDataSource` with two methods:
+
+- `lookupPostalCode(request, options?)`
+- `searchAddress(request, options?)`
+
+Both methods return `Promise<Page<JapanAddress>>`.
+
 ```tsx
-import { useJapanPostalCode } from "@cp949/japanpost-react";
-import type { JapanAddressDataSource } from "@cp949/japanpost-react";
-import { createJapanAddressError } from "@cp949/japanpost-react";
+import {
+  PostalCodeInput,
+  createJapanAddressError,
+  useJapanPostalCode,
+  type JapanAddress,
+  type JapanAddressDataSource,
+  type JapanAddressRequestOptions,
+  type Page,
+} from "@cp949/japanpost-react";
+
+function isAbortError(error: unknown): boolean {
+  return error instanceof DOMException && error.name === "AbortError";
+}
+
+function isPagePayload(payload: unknown): payload is Page<JapanAddress> {
+  return (
+    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"
+  );
+}
+
+async function readPage(
+  path: string,
+  request: unknown,
+  options?: JapanAddressRequestOptions,
+): Promise<Page<JapanAddress>> {
+  let response: Response;
+
+  try {
+    response = 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 (!response.ok) {
+    throw createJapanAddressError(
+      "data_source_error",
+      `Request failed with status ${response.status}`,
+      { status: response.status },
+    );
+  }
+
+  let payload: unknown;
+
+  try {
+    payload = await response.json();
+  } catch (error) {
+    throw createJapanAddressError(
+      "bad_response",
+      "Response payload was not valid JSON",
+      { cause: error },
+    );
+  }
+
+  if (!isPagePayload(payload)) {
+    throw createJapanAddressError(
+      "bad_response",
+      "Response payload must include a valid page payload",
+    );
+  }
+
+  return payload;
+}
 
-// 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;
+  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;
+  searchAddress(request, options) {
+    return readPage("/q/japanpost/addresszip", request, options);
   },
 };
 
-export function PostalForm() {
+export function PostalCodeLookupExample() {
   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>
-      ))}
+      <PostalCodeInput
+        buttonLabel="Search"
+        label="Postal code"
+        onSearch={(postalCode) => {
+          void search({ postalCode });
+        }}
+      />
+
+      {loading ? <p>Loading...</p> : null}
+      {error ? <p>{error.message}</p> : null}
+
+      <ul>
+        {(data?.elements ?? []).map((address) => (
+          <li key={`${address.postalCode}-${address.address}`}>
+            {address.address}
+          </li>
+        ))}
+      </ul>
     </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,
-});
-```
+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.
 
-### useJapanAddressSearch
+## Core Contract
 
-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:
+`Page<T>` is the result shape shared by the hooks and the reference backend:
 
 ```ts
-type JapanAddressRequestOptions = {
-  signal?: AbortSignal;
+type Page<T> = {
+  elements: T[];
+  totalElements: number;
+  pageNumber: number;
+  rowsPerPage: number;
 };
 ```
 
-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
+`JapanAddress` is the normalized address shape returned by the package:
 
-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;
-  },
+```ts
+type JapanAddress = {
+  postalCode: string;
+  prefecture: string;
+  prefectureKana?: string;
+  city: string;
+  cityKana?: string;
+  town: string;
+  townKana?: string;
+  address: string;
+  provider: "japan-post";
 };
-
-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자리일 때만 하이픈을 넣습니다.
-그 외 길이에서는 하이픈을 추가하지 않고 숫자만 남긴 값을 그대로 반환합니다.
+The hooks keep this page payload as-is, so consumers read
+`data?.elements`, `data?.totalElements`, `data?.pageNumber`, and
+`data?.rowsPerPage` directly.
 
 ## Hooks
 
-### useJapanPostalCode
+### `useJapanPostalCode`
 
-우편번호로 주소를 조회합니다.
+- Accepts `string` or `JapanPostalCodeSearchInput`
+- Normalizes the input to digits before calling the data source
+- Allows `3-7` digits, so prefix lookup is possible
+- Builds `{ postalCode, pageNumber: 0, rowsPerPage: 100 }` by default
+- Exposes `loading`, `data`, `error`, `search`, `cancel`, and `reset`
 
 ```tsx
-const { loading, data, error, search, reset } = useJapanPostalCode({
-  dataSource,
+const postalCode = useJapanPostalCode({ dataSource });
+
+void postalCode.search("100-0001");
+void postalCode.search({
+  postalCode: "1000001",
+  pageNumber: 1,
+  rowsPerPage: 10,
+  includeParenthesesTown: true,
 });
 ```
 
-### useJapanAddressSearch
+### `useJapanAddressSearch`
 
-자유 형식 키워드로 주소를 검색하며 `debounceMs`를 지원합니다.
+- Accepts `string` or `JapanAddressSearchInput`
+- Supports free-form search and structured fields in the same request type
+- Rejects a fully blank query before calling the data source
+- Omits `includeCityDetails` and `includePrefectureDetails` unless you set them
+- Supports `debounceMs`
+- Exposes `loading`, `data`, `error`, `search`, `cancel`, and `reset`
 
 ```tsx
-const { loading, data, error, search, reset } = useJapanAddressSearch({
+const addressSearch = useJapanAddressSearch({
   dataSource,
   debounceMs: 300,
 });
+
+void addressSearch.search("千代田");
+void addressSearch.search({
+  prefName: "東京都",
+  cityName: "千代田区",
+  pageNumber: 0,
+  rowsPerPage: 10,
+});
 ```
 
-### useJapanAddress
+### `useJapanAddress`
 
-우편번호 조회와 키워드 검색을 하나의 훅으로 합칩니다.
+- Combines postal-code lookup and address search in one hook
+- Reuses the same `dataSource`
+- Exposes `searchByPostalCode`, `searchByAddressQuery`, and `reset`
+- Returns `data` and `error` for the currently active search mode only
 
 ```tsx
-const { loading, data, error, searchByPostalCode, searchByKeyword, reset } =
-  useJapanAddress({ dataSource, debounceMs: 300 });
-```
-
-모든 훅은 런타임에서 `dataSource`가 필요합니다.
+const address = useJapanAddress({
+  dataSource,
+  debounceMs: 300,
+});
 
-## 에러 처리 메모
+void address.searchByPostalCode("1000001");
+void address.searchByAddressQuery({
+  addressQuery: "千代田",
+  pageNumber: 0,
+  rowsPerPage: 10,
+});
+```
 
-`JapanAddressDataSource`의 두 메서드는 모두 `JapanAddress[]`를 직접
-반환해야 합니다. 각 훅은 그 배열을 받아 `{ postalCode, addresses }`,
-`{ query, addresses }` 형태의 결과 객체를 조합합니다.
+## Headless Components
 
-두 메서드는 선택적인 두 번째 인자도 받을 수 있습니다.
+### `PostalCodeInput`
 
-```ts
-type JapanAddressRequestOptions = {
-  signal?: AbortSignal;
-};
-```
+- Renders a `<form>` with `<label>`, `<input>`, and `<button>`
+- Supports controlled and uncontrolled usage
+- Calls `onSearch` with a normalized digits-only postal code
+- Defaults `inputMode="numeric"` unless overridden with `inputProps`
 
-훅은 superseded 요청, `reset()`, unmount 정리 상황에서 이전 요청을 취소할 수
-있도록 `signal`을 전달합니다. 백엔드 레이어가 abort를 지원하면 그대로 활용할 수
-있습니다.
+### `AddressSearchInput`
 
-권장 에러 코드 매핑:
+- Renders the same minimal form structure
+- Supports controlled and uncontrolled usage
+- Calls `onSearch` with a trimmed query string
 
-| 상황 | 권장 코드 |
-| --- | --- |
-| 잘못된 우편번호 입력 | `invalid_postal_code` |
-| 빈 주소 검색어 | `invalid_query` |
-| 네트워크 실패 | `network_error` |
-| 요청 중단 / 타임아웃 | `timeout` |
-| 검색 결과 없음 | `not_found` |
-| 성공 응답 shape 이상 | `bad_response` |
-| 그 외 백엔드 오류 | `data_source_error` |
+Both components accept:
 
-이 저장소의 참고 demo 흐름에서는 예시 `dataSource`가 `400 /searchcode/...`를
-`invalid_postal_code`, `400 /addresszip?...`를 `invalid_query`, `404`를
-`not_found`, `504`를 `timeout`으로 매핑합니다.
+- `inputProps` for the rendered `<input>`
+- `buttonProps` for the rendered `<button>`
 
-## Headless 컴포넌트
+## Data Source Integration
 
-`PostalCodeInput`, `AddressSearchInput`은 스타일 없이 동작과 DOM 구조만
-제공하므로, 앱의 디자인 시스템에 맞게 직접 꾸밀 수 있습니다.
+The package exports types for both sides of the integration:
 
-두 컴포넌트는 네이티브 props 전달도 지원합니다.
+- `JapanAddressDataSource`
+- `JapanPostSearchcodeRequest`
+- `JapanPostAddresszipRequest`
+- `JapanPostalCodeSearchInput`
+- `JapanAddressSearchInput`
+- `JapanAddressRequestOptions`
 
-- `inputProps`: 실제 `<input />`에 전달
-- `buttonProps`: 실제 `<button />`에 전달
+The optional second argument to each data-source method is:
 
-따라서 `id`, `name`, `placeholder`, `aria-*`, `autoComplete`, `className`,
-폼 연동용 속성을 직접 넘길 수 있습니다. `PostalCodeInput`은 별도 override가
-없으면 기본적으로 `inputMode="numeric"`를 사용합니다.
+```ts
+type JapanAddressRequestOptions = {
+  signal?: AbortSignal;
+};
+```
 
-## Data Source와 서버 연동
+The hooks pass `signal` so your data source can cancel superseded requests,
+`cancel()` calls, `reset()` calls, and unmount cleanup.
 
-이 패키지는 자체 백엔드 서버와 함께 사용하는 것을 권장합니다. Japan Post
-공식 연동은 토큰 기반 인증을 사용하므로, 브라우저에서 업스트림 자격증명을
-직접 보관하면 안 됩니다. 현재 지원 방식은 실제 서버 연동뿐입니다.
+This repository's reference backend uses these routes:
 
-이 저장소의 `apps/minimal-api`는 로컬 기준 참고 서버 구현입니다. Japan Post
-API ver 2.0을 감싸며, 로컬 개발과 통합 확인 용도로 쓰는 구성을 목표로
-합니다. demo의 `/minimal-api` 경로는 개발 편의를 위한 로컬 경로 연결입니다.
-업스트림 payload에 구조화된 주소 필드와 원본 전체 주소 문자열인 `address`가 함께
-있더라도, 참고 서버는 둘을 그대로 이어붙이지 않고 중복 없는 표시 주소를
-우선 사용합니다.
+- `POST /q/japanpost/searchcode`
+- `POST /q/japanpost/addresszip`
 
-timeout 메시지는 토큰 발급 단계와 실제 조회 단계 중 어느 쪽에서 timeout이
-발생했는지에 따라 달라질 수 있지만, 두 경우 모두 `timeout` 코드로 다루면
-됩니다.
+But those route names are not part of the package API. They are just the
+example used by `apps/demo` and `apps/minimal-api`.
 
-## SSR
+## Constraints And Notes
 
-`dataSource` 구현에서는 서버 측 API를 사용하고, 토큰 교환과 업스트림 서명은
-서버에서만 처리하세요. React 훅과 UI 컴포넌트는 클라이언트 컴포넌트에서
-사용하는 것이 안전합니다.
+- `dataSource` is required at runtime for all hooks.
+- `isValidJapanPostalCode()` checks for an exact 7-digit postal code after
+  normalization. `useJapanPostalCode()` is less strict and accepts `3-7`
+  digits for prefix lookup.
+- `formatJapanPostalCode()` inserts a hyphen only when the normalized value is
+  exactly 7 digits.
+- `cancel()` on `useJapanPostalCode()` and `useJapanAddressSearch()` aborts the
+  in-flight request but keeps the latest settled `data` and `error`.
+- `reset()` clears both `data` and `error`.
+- The package does not require a backend to return `404` for misses. Returning
+  `200` with an empty page is also compatible with the hook contract.
+- Use your own server-side API in the `dataSource` implementation. Keep Japan
+  Post credentials and token exchange on the server side.