entity-server-client 0.2.5 → 0.3.0

package/docs/apis.md

@@ -1,790 +1,25 @@
-# 함수별 사용법
+# entity-server-client API 문서
 
-## 목차
-
-| 구분               | 바로가기                                 |
-| ------------------ | ---------------------------------------- |
-| import             | [import](#import)                        |
-| 서버 헬스체크      | [서버 헬스체크](#서버-헬스체크)          |
-| 인스턴스 생성/설정 | [인스턴스 생성/설정](#인스턴스-생성설정) |
-| 인증               | [인증](#인증)                            |
-| 트랜잭션           | [트랜잭션](#트랜잭션)                    |
-| 엔티티 CRUD / 조회 | [엔티티 CRUD / 조회](#엔티티-crud--조회) |
-| 푸시 관련          | [푸시 관련](#푸시-관련)                  |
-| 암호화 패킷 처리   | [암호화 패킷 처리](#암호화-패킷-처리)    |
-| React Hook         | [React Hook](#react-hook)                |
-
----
-
-## import
-
-```ts
-import {
-    EntityServerClient,
-    entityServer,
-    type EntityListParams,
-    type EntityListResult,
-    type EntityHistoryRecord,
-    type EntityQueryRequest,
-    type RegisterPushDeviceOptions,
-    type EntityServerClientOptions,
-} from "entity-server-client";
-```
-
-React Hook:
-
-```ts
-import { useEntityServer } from "entity-server-client/react";
-```
-
----
-
-## 서버 헬스체크
-
-### 개요
-
-앱 시작 시 서버의 패킷 암호화 설정을 감지하여 클라이언트 설정을 자동으로 맞춥니다.
-
-**헬스체크 응답:**
-
-```json
-{
-    "ok": true,
-    "packet_encryption": false
-}
-```
-
-### 자동 초기화 (권장)
-
-**admin-web 예시:**
-
-```ts
-import { checkServerHealth, entityServer } from "entity-server-client";
-
-// 앱 초기화 시 한 번 실행 (예: App.tsx mount, main.tsx 초기화)
-const health = await checkServerHealth();
-// → 서버의 packet_encryption: true 이면
-//   클라이언트의 encryptRequests: true 로 자동 설정됨
-```
-
-**수동 초기화:**
-
-```ts
-const res = await fetch("/v1/health");
-const { packet_encryption } = await res.json();
-
-if (packet_encryption) {
-    entityServer.configure({ encryptRequests: true });
-}
-```
-
-> **중요:** `packetMagicLen` 값은 클라이언트가 미리 알고 있어야 합니다.
-> 빌드 시점에 `VITE_PACKET_MAGIC_LEN` 환경변수로 결정되며,
-> 서버와 일치해야 올바르게 복호화됩니다.
-
----
-
-## 인스턴스 생성/설정
-
-### `new EntityServerClient(options?)`
-
-| 옵션               | 타입                               | 기본값                                                 | 설명                                                                                                                                                                                 |
-| ------------------ | ---------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `baseUrl`          | `string`                           | `VITE_ENTITY_SERVER_URL` 또는 `http://localhost:47200` | 서버 주소                                                                                                                                                                            |
-| `token`            | `string`                           | `""`                                                   | JWT Access Token                                                                                                                                                                     |
-| `packetMagicLen`   | `number`                           | `VITE_PACKET_MAGIC_LEN` 또는 `4`                       | 암호화 패킷 magic 바이트 길이                                                                                                                                                        |
-| `encryptRequests`  | `boolean`                          | `false`                                                | `true` 로 설정하면 인증된 POST/PUT/PATCH 요청 바디를 XChaCha20-Poly1305 로 암호화하여 전송합니다. 서버에서 `requirePacketEncryption = true` 로 설정된 경우 반드시 활성화해야 합니다. |
-| `keepSession`      | `boolean`                          | `false`                                                | `true`이면 `login()` 성공 후 Access Token 만료 전에 자동으로 갱신합니다.                                                                                                             |
-| `refreshBuffer`    | `number`                           | `60`                                                   | 만료 몇 초 전에 갱신을 시도할지 설정합니다. 예: `expires_in=3600`, `refreshBuffer=60` → 3540초 후 갱신                                                                               |
-| `onTokenRefreshed` | `(accessToken, expiresIn) => void` | —                                                      | 자동 갱신 성공 시 호출됩니다. 새 `access_token`을 받아 앱 레벨 저장소에 업데이트하세요.                                                                                              |
-| `onSessionExpired` | `(error: Error) => void`           | —                                                      | 세션 유지 갱신 실패 시 호출됩니다 (refresh_token 만료 등). 로그인 페이지로 이동하는 등의 처리를 여기서 합니다.                                                                       |
-
-```ts
-// 직접 생성
-const client = new EntityServerClient({
-    baseUrl: "https://api.example.com",
-    token: "eyJhbGciOi...",
-    packetMagicLen: 4,
-    encryptRequests: true, // 요청 바디 암호화 활성화
-});
-
-// 싱글톤 (환경변수 자동 읽기)
-import { entityServer } from "entity-server-client";
-```
-
-### `configure(options)`
-
-런타임에 설정을 갱신합니다.
-
-```ts
-client.configure({
-    baseUrl: "https://api.example.com",
-    token: "new-access-token",
-    packetMagicLen: 6,
-    encryptRequests: true,
-});
-```
-
-### `setToken(token)` / `setPacketMagicLen(length)` / `getPacketMagicLen()`
-
-```ts
-client.setToken("eyJhbGciOi...");
-client.setPacketMagicLen(4);
-const len = client.getPacketMagicLen(); // 4
-```
-
----
-
-## 인증
-
-### `login(email, password)`
-
-이메일 + 비밀번호로 로그인합니다. 성공 시 내부 토큰이 자동으로 설정됩니다.
-
-```ts
-const auth = await client.login("admin@example.com", "password");
-// auth.access_token   — 이후 요청에 자동 사용됨
-// auth.refresh_token  — 만료 후 재발급에 사용
-// auth.expires_in     — 만료까지 남은 초
-```
-
-### `refreshToken(refreshToken)`
-
-Refresh Token으로 Access Token을 재발급받습니다.
-앱이 명시적으로 호출해야 하며, 성공하면 내부 `this.token`을 새 Access Token으로 교체합니다.
-
-> **패키지는 401을 감지해 자동으로 `refreshToken()`을 호출하지 않습니다.**
-> 401 발생 시 앱이 직접 catch해서 호출해야 합니다.
-
-```ts
-const result = await client.refreshToken(auth.refresh_token);
-// 성공 → this.token이 result.access_token으로 교체됨
-// result.access_token
-// result.expires_in
-```
-
-### `logout(refreshToken)`
-
-서버에 로그아웃을 요청하고 내부 토큰을 초기화합니다.
-Refresh Token을 서버에 전달해 무효화하므로 해당 토큰으로 더 이상 재발급이 불가능합니다.
-Refresh Token이 이미 만료된 경우에도 서버는 성공으로 응답합니다.
-
-```ts
-await client.logout(auth.refresh_token);
-// 이후 client 내부 token = "" 으로 초기화됨
-```
-
-### 토큰 만료 처리
-
-**패키지가 자동으로 처리하는 것:**
-
-| 동작                  | 내부 토큰 갱신 |
-| --------------------- | -------------- |
-| `login()` 성공        | ✅ 자동 세팅   |
-| `refreshToken()` 성공 | ✅ 자동 교체   |
-| `logout()` 호출       | ✅ `""` 초기화 |
-
-**패키지가 처리하지 않는 것:**
-
-- **401 자동 재시도 없음**: access_token이 만료되어 서버가 401을 반환하면 패키지는 에러를 throw합니다. 앱이 직접 잡아서 `refreshToken()`을 호출하고 재시도해야 합니다.
-- **토큰 영속성 없음**: 페이지 새로고침 시 싱글톤 인스턴스가 초기화되어 내부 token이 `""` 로 리셋됩니다. 앱이 직접 복원 후 `setToken()` 또는 `configure({ token })` 으로 재세팅해야 합니다.
-
-**401 발생 후 앱의 처리 흐름:**
-
-```
-API 요청 → 401 응답 → entityServer.refreshToken(refresh_token) 호출
-                              ↓ 성공              ↓ 실패 (refresh_token도 만료)
-               setToken(new_access_token)      로그인 페이지로 이동
-               원래 요청 재시도
-```
-
-**주의:** `refreshToken()`이 성공해 패키지 내부 토큰이 교체되더라도, 앱 내 다른 HTTP 클라이언트(axios 등)에는 별도로 토큰을 전달해야 합니다.
-
-### `keepSession` — 세션 유지 (Silent Refresh)
-
-`keepSession: true` 옵션 설정 시, `login()` 성공 후 만료 `refreshBuffer`초 전에 패키지 내부 타이머가 자동으로 `refreshToken()`을 호출합니다.
-갱신이 성공하면 타이머를 다시 예약해 로그인 상태를 계속 유지합니다.
-`logout()` 또는 `stopKeepSession()` 호출 시 타이머가 정리됩니다.
-
-```ts
-entityServer.configure({
-    keepSession: true,
-    refreshBuffer: 60, // 만료 60초 전에 갱신 (기본값)
-    onTokenRefreshed: (accessToken, expiresIn) => {
-        // 갱신 성공 — 앱 레벨 저장소 업데이트
-        localStorage.setItem("auth_access_token", accessToken);
-    },
-    onSessionExpired: (error) => {
-        // refresh_token 만료 등으로 갱신 실패
-        console.error("세션 만료:", error);
-        window.location.href = "/login";
-    },
-});
-
-// 이후 login() 하면 타이머 자동 시작
-const auth = await entityServer.login(email, password);
-// expires_in=3600이면 3540초 후 자동 갱신, 이후 반복
-```
-
-**수동으로 타이머 중지:**
-
-```ts
-entityServer.stopKeepSession();
-```
-
-> **페이지 새로고침 시**: 타이머는 메모리에만 존재하므로 새로고침 시 초기화됩니다.
-> `useEntityServer`의 `resumeSession` 옵션을 사용하면 페이지 새로고침 후에도 세션을 자동으로 복원할 수 있습니다.
-
----
-
-## 트랜잭션
-
-여러 submit/delete를 하나의 DB 트랜잭션으로 묶습니다.
-트랜잭션은 **5분 TTL**을 가집니다. 이 안에 commit 또는 rollback을 해야 합니다.
-
-```
-transStart → submit/delete (여러 개) → transCommit
-                                      └→ transRollback (실패 시)
-```
-
-### `transStart()`
-
-트랜잭션을 시작하고 내부 활성 트랜잭션 ID를 저장합니다.
-이후 `submit()`/`delete()`는 `X-Transaction-ID` 헤더를 자동 포함합니다.
-
-```ts
-const txId = await client.transStart();
-```
-
-### `transCommit(transactionId?)`
-
-큐에 쌓인 모든 작업을 단일 DB 트랜잭션으로 일괄 실행합니다.
-하나라도 실패하면 전체 ROLLBACK됩니다.
-
-```ts
-await client.transStart();
-await client.submit("order", { product_seq: 1, qty: 2 });
-await client.submit("inventory", { seq: 1, stock: 48 });
-const result = await client.transCommit();
-// result.results → [{ entity: "order", action: "submit", seq: 55 }, ...]
-```
-
-> **트랜잭션 중 submit 응답**: commit 전에는 `{ ok: true, queued: true, seq: "$tx.0" }` 형태의
-> placeholder가 반환됩니다. `$tx.0`, `$tx.1` 값은 commit 시 실제 seq로 자동 치환되므로
-> 후속 submit의 외래키 값으로 그대로 사용할 수 있습니다.
-
-### `transRollback(transactionId?)`
-
-- 아직 commit 전 (큐에 남아있음): 큐를 버립니다. DB에 아무 변경 없음.
-- 이미 commit 후: history 기반으로 전체 되돌립니다.
-
-```ts
-try {
-    await client.transStart();
-    await client.submit("order", { ... });
-    await client.transCommit();
-} catch (e) {
-    await client.transRollback(); // 활성 트랜잭션 자동 참조
-}
-```
-
----
-
-## 엔티티 CRUD / 조회
-
-### `get(entity, seq, opts?)`
-
-시퀀스 ID로 엔티티 단건을 조회합니다.
-
-| 옵션        | 타입      | 설명                                      |
-| ----------- | --------- | ----------------------------------------- |
-| `skipHooks` | `boolean` | `true`이면 `after_get` 훅을 실행하지 않음 |
-
-```ts
-const result = await client.get<Account>("account", 1);
-result.data; // Account 타입 객체
-```
-
----
-
-### `find(entity, conditions?, opts?)`
-
-조건(conditions)으로 첫 번째 일치 레코드를 조회합니다.  
-`data` 컬럼을 **항상 완전히 복호화**하여 반환합니다. 레코드가 없으면 `404` 에러가 됩니다.
-
-| 파라미터     | 타입                      | 설명                                |
-| ------------ | ------------------------- | ----------------------------------- |
-| `conditions` | `Record<string, unknown>` | 검색 조건 (인덱스 필드만 조건 가능) |
-| `skipHooks`  | `boolean`                 | `true`이면 훅 실행 건너뛰기         |
-
-```ts
-// 이메일로 계정 단건 조회
-const result = await client.find<Account>("account", {
-    email: "hong@example.com",
-});
-result.data; // Account 전체 필드 (passwd 포함)
-
-// skipHooks 옵션
-const result = await client.find<Account>(
-    "account",
-    { code: "A001" },
-    { skipHooks: true },
-);
-```
-
-> **`get` vs `find`**
->
-> - `get(entity, seq)`: seq(일련번호)를 정확히 알고 있을 때 빠르게 조회
-> - `find(entity, conditions)`: 조건으로 검색, 항상 data 전체 복호화 반환
-
----
-
-### `list(entity, params?)`
-
-페이지네이션/정렬/필터 조건으로 엔티티 목록을 조회합니다.
-
-| 파라미터     | 타입                      | 기본값  | 설명                                                |
-| ------------ | ------------------------- | ------- | --------------------------------------------------- |
-| `page`       | `number`                  | `1`     | 페이지 번호                                         |
-| `limit`      | `number`                  | `20`    | 페이지당 레코드 수 (최대 1000)                      |
-| `orderBy`    | `string`                  | —       | 정렬 기준 필드명. `-` 접두사로 내림차순 지정 가능   |
-| `orderDir`   | `"ASC" \| "DESC"`         | `"ASC"` | 정렬 방향 (`orderBy: "-field"`와 동일 효과)         |
-| `fields`     | `string[]`                | —       | 반환할 필드 목록 (**미지정 시 인덱스 필드만 반환**) |
-| `conditions` | `Record<string, unknown>` | —       | 필터 조건                                           |
-
-#### `fields` — 반환 필드 지정
-
-`fields`는 `entity.json`의 `index`로 선언된 필드명만 지정할 수 있습니다.
-존재하지 않는 필드를 지정하면 서버 에러가 발생합니다.
-
-| 값                  | 설명                                                           |
-| ------------------- | -------------------------------------------------------------- |
-| 미지정 (기본값)     | 인덱스 선언 필드만 반환. **복호화를 건너뛰어 가장 빠름**       |
-| `["*"]`             | 전체 필드 반환 (복호화 수행)                                   |
-| `["name", "email"]` | 지정한 인덱스 필드만 반환. 모두 인덱스 필드면 역시 복호화 생략 |
-
-> `seq`, `created_time`, `updated_time`, `license_seq`는 `fields` 지정 여부와 무관하게 항상 포함됩니다.
-
-#### `conditions` — 필터 조건
-
-인덱스 테이블의 필드(`index` / `hash` / `unique`로 선언된 필드)에만 조건을 걸 수 있습니다.
-인덱스에 없는 필드로 필터를 걸면 동작하지 않거나 에러가 발생합니다.
-
-```ts
-// 기본값 (인덱스 필드만, 가장 빠름)
-const result = await client.list("account");
-result.data.items; // 레코드 배열
-result.data.total; // 필터 조건 일치 전체 건수
-result.data.page; // 현재 페이지
-result.data.limit; // 페이지당 레코드 수
-
-// 정렬 + 필터 + 필드 선택
-const result = await client.list("account", {
-    page: 1,
-    limit: 20,
-    orderBy: "created_time",
-    orderDir: "DESC",
-    fields: ["seq", "name", "email"], // index 필드만 → 복호화 생략
-    conditions: { status: "active" },
-});
+각 섹션은 별도 파일로 분리되어 있습니다.
 
-// 전체 필드 반환 (fields: ["*"])
-const full = await client.list("account", {
-    fields: ["*"],
-    conditions: { status: "active" },
-});
-
-// orderBy에 - 접두사로 내림차순 (orderDir: "DESC"와 동일)
-const desc = await client.list("account", { orderBy: "-created_time" });
-```
-
----
-
-### `count(entity, conditions?)`
-
-레코드 건수를 조회합니다. `conditions`는 `list()`와 동일한 필터 규칙을 따릅니다.
-
-```ts
-const total = await client.count("account");
-total.count; // 전체 건수
-
-const active = await client.count("account", { status: "active" });
-active.count; // 조건 일치 건수
-```
-
----
-
-### `query(entity, req)`
-
-커스텀 SQL로 엔티티를 조회합니다.
-
-**제약사항**:
-
-- SELECT 쿼리만 허용 (INSERT/UPDATE/DELETE 불가)
-- 인덱스 테이블(`entity_idx_*`)만 접근 가능. 암호화된 본문 필드는 조회 불가
-- `SELECT *` 불가. 인덱스 선언 필드만 SELECT 가능
-- 최대 반환 건수: 1000
-
-`entity`는 URL 라우트 경로용 기본 엔티티명으로, 실제 조회 대상은 SQL에서 결정됩니다.
-
-| 필드     | 타입        | 설명                                            |
-| -------- | ----------- | ----------------------------------------------- |
-| `sql`    | `string`    | SELECT SQL문. 사용자 입력은 반드시 `?`로 바인딩 |
-| `params` | `unknown[]` | `?` 플레이스홀더에 바인딩할 값 배열             |
-| `limit`  | `number`    | 최대 반환 건수 (최대 1000)                      |
-
-응답: `{ ok: true, data: { items: T[], count: number } }`
-
-```ts
-// 단일 엔티티
-const result = await client.query("account", {
-    sql: "SELECT seq, name, email FROM account WHERE status = ?",
-    params: ["active"],
-    limit: 50,
-});
-result.data.items; // 레코드 배열
-result.data.count; // 반환된 건수
-
-// JOIN으로 여러 엔티티 조합
-const joined = await client.query("order", {
-    sql: `
-        SELECT o.seq, o.status, u.name AS user_name, u.email
-        FROM order o
-        JOIN account u ON u.data_seq = o.account_seq
-        WHERE o.status = ?
-        ORDER BY o.seq DESC
-    `,
-    params: ["pending"],
-    limit: 100,
-});
-```
-
-> SQL Injection 방지: 사용자 입력값은 반드시 `params`로 바인딩하세요.
-
----
-
-### `submit(entity, data, opts?)`
-
-엔티티를 생성 또는 수정합니다.
-
-- `data`에 `seq`가 **없으면** INSERT
-- `data`에 `seq`가 **있으면** UPDATE
-- `unique` 선언 필드 기준 중복 감지 시 자동 UPDATE (upsert)
-
-응답의 `seq`는 생성/수정된 레코드의 시퀀스 ID입니다.
-
-| 옵션            | 타입      | 설명                                                              |
-| --------------- | --------- | ----------------------------------------------------------------- |
-| `transactionId` | `string`  | 수동 트랜잭션 ID. 미지정 시 활성 트랜잭션 자동 사용               |
-| `skipHooks`     | `boolean` | `true`이면 `before/after_insert`, `before/after_update` 훅 미실행 |
-
-```ts
-// INSERT
-const res = await client.submit("account", {
-    name: "홍길동",
-    email: "hong@example.com",
-});
-res.seq; // 생성된 seq
-
-// UPDATE (seq 포함 시)
-await client.submit("account", { seq: 1, name: "홍길순" });
-
-// 훅 없이 저장
-await client.submit("account", { name: "테스트" }, { skipHooks: true });
-
-// 트랜잭션 내에서 — seq placeholder 활용
-await client.transStart();
-const r1 = await client.submit("order", { product_seq: 1, qty: 2 });
-// r1.seq → "$tx.0" (commit 후 실제 seq로 치환)
-await client.submit("order_item", { order_seq: r1.seq, name: "상품A" });
-await client.transCommit();
-```
-
----
-
-### `delete(entity, seq, opts?)`
-
-엔티티를 삭제합니다.
-
-| 옵션            | 타입      | 기본값  | 설명                                                      |
-| --------------- | --------- | ------- | --------------------------------------------------------- |
-| `hard`          | `boolean` | `false` | `true`이면 완전 삭제. `false`이면 소프트 삭제 (복원 가능) |
-| `transactionId` | `string`  | —       | 수동 트랜잭션 ID. 미지정 시 활성 트랜잭션 자동 사용       |
-| `skipHooks`     | `boolean` | `false` | `true`이면 `before/after_delete` 훅 미실행                |
-
-> **소프트 삭제 (기본)**: DB에서 제거하지 않고 삭제 표시만 합니다. `rollback()`으로 복원 가능합니다.
-> **하드 삭제**: DB에서 완전히 제거됩니다. 복원 불가능합니다.
-
-```ts
-// 소프트 삭제 (기본)
-const res = await client.delete("account", 2);
-res.deleted; // 삭제된 seq
-
-// 하드 삭제
-await client.delete("account", 3, { hard: true });
-```
-
----
-
-### `history(entity, seq, params?)`
-
-엔티티 단건의 변경 이력을 조회합니다. `params`는 `page`, `limit`만 지원합니다.
-
-응답 `data.items`의 각 레코드 구조:
-
-| 필드             | 타입           | 설명                                                                                 |
-| ---------------- | -------------- | ------------------------------------------------------------------------------------ |
-| `seq`            | `number`       | 이력 레코드 seq (`rollback()` 호출 시 사용)                                          |
-| `action`         | `string`       | `"INSERT"` \| `"UPDATE"` \| `"DELETE_SOFT"` \| `"DELETE_HARD"` \| `"ROLLBACK"`       |
-| `data_snapshot`  | `T \| null`    | **after 통일 모델**: INSERT/UPDATE → 변경 **후** 데이터, DELETE → 삭제 **전** 데이터 |
-| `changed_by`     | `number\|null` | 변경한 계정 seq. 시스템 변경이면 `null`                                              |
-| `changed_time`   | `string`       | 변경 시각 (ISO 8601)                                                                 |
-| `transaction_id` | `string`       | 해당 변경이 속한 트랜잭션 ID. rollback 시 이 ID 기준으로 전체 롤백됨                 |
-
-```ts
-const result = await client.history("account", 1, { page: 1, limit: 50 });
-result.data.total; // 전체 이력 건수
-result.data.items[0].action; // "UPDATE"
-result.data.items[0].data_snapshot; // 변경 후 데이터
-result.data.items[0].transaction_id; // "TX-20260201-abc123"
-```
-
----
-
-### `rollback(entity, historySeq)`
-
-특정 이력 레코드의 `transaction_id`를 조회해 **해당 트랜잭션 전체**를 롤백합니다.
-
-한 번의 트랜잭션에 여러 엔티티가 변경됐다면 모든 엔티티가 함께 되돌아갑니다.
-
-```ts
-// history()로 이력 seq 조회 후 rollback
-const hist = await client.history("account", 1);
-const targetHistorySeq = hist.data.items[0].seq;
-await client.rollback("account", targetHistorySeq);
-```
-
----
-
-## 푸시 관련
-
-### `push(pushEntity, payload, opts?)`
-
-`submit()`의 별칭입니다. 푸시 관련 엔티티에 데이터를 제출합니다.
-
-```ts
-await client.push("push_message", {
-    title: "새 알림",
-    body: "내용",
-    account_seq: 1,
-});
-```
-
-### `pushLogList(params?)`
-
-`push_log` 엔티티의 목록을 조회합니다. `list()`의 별칭입니다.
-
-```ts
-const logs = await client.pushLogList({
-    page: 1,
-    limit: 30,
-    orderBy: "-created_time",
-    conditions: { account_seq: 1 },
-});
-logs.data.items;
-logs.data.total;
-```
-
-### `registerPushDevice(accountSeq, deviceId, pushToken, opts?)`
-
-`account_device` 엔티티에 디바이스를 등록합니다.
-
-| 옵션             | 타입      | 설명                              |
-| ---------------- | --------- | --------------------------------- |
-| `platform`       | `string`  | 플랫폼 (예: `"web"`, `"android"`) |
-| `deviceType`     | `string`  | 디바이스 종류 (예: `"mobile"`)    |
-| `browser`        | `string`  | 브라우저명 (예: `"Chrome"`)       |
-| `browserVersion` | `string`  | 브라우저 버전                     |
-| `pushEnabled`    | `boolean` | 푸시 수신 여부. 기본값 `true`     |
-| `transactionId`  | `string`  | 트랜잭션 ID                       |
-
-```ts
-const res = await client.registerPushDevice(
-    1,
-    "device-uuid-001",
-    "fcm-token-abc",
-    {
-        platform: "web",
-        browser: "Chrome",
-        browserVersion: "120",
-        pushEnabled: true,
-    },
-);
-res.seq; // 등록된 account_device seq
-```
-
-### `updatePushDeviceToken(deviceSeq, pushToken, opts?)`
-
-등록된 디바이스의 푸시 토큰을 갱신합니다.
-
-```ts
-await client.updatePushDeviceToken(10, "new-fcm-token", { pushEnabled: true });
-```
-
-### `disablePushDevice(deviceSeq, opts?)`
-
-디바이스의 푸시 수신을 비활성화합니다 (`push_enabled: false`).
-
-```ts
-await client.disablePushDevice(10);
-```
-
----
-
-## React Hook
-
-### `useEntityServer(options?)`
-
-React 컴포넌트에서 EntityServerClient를 사용할 때 권장되는 훅입니다.
-`submit` / `del` / `query` 의 `isPending`, `error` 상태를 자동으로 관리합니다.
-
-```ts
-import { useEntityServer } from "entity-server-client/react";
-```
-
-#### 옵션
-
-| 옵션               | 타입                                | 기본값 | 설명                                                                                            |
-| ------------------ | ----------------------------------- | ------ | ----------------------------------------------------------------------------------------------- |
-| `singleton`        | `boolean`                           | `true` | `true`이면 전역 `entityServer` 인스턴스 사용                                                    |
-| `baseUrl`          | `string`                            | —      | 서버 주소 (singleton일 때 `configure()` 호출)                                                   |
-| `packetMagicLen`   | `number`                            | —      | 암호화 패킷 magic 바이트 길이                                                                   |
-| `token`            | `string`                            | —      | JWT Access Token                                                                                |
-| `tokenResolver`    | `() => string \| undefined \| null` | —      | 렌더 시점에 토큰을 동적으로 주입하는 함수                                                       |
-| `keepSession`      | `boolean`                           | —      | 세션 유지 활성화 (인덱스 참고)                                                                  |
-| `onTokenRefreshed` | `(accessToken, expiresIn) => void`  | —      | 세션 유지 성공 콜백                                                                             |
-| `onSessionExpired` | `(error: Error) => void`            | —      | 세션 만료 콜백 (refresh_token 만료 등)                                                          |
-| `resumeSession`    | `string`                            | —      | 저장된 refresh_token. 마운트 시 `refreshToken()` 호출해 토큰 복원 + `keepSession` 타이머 재시작 |
-
-#### 반환값
-
-| 필드        | 타입                 | 설명                                                |
-| ----------- | -------------------- | --------------------------------------------------- |
-| `client`    | `EntityServerClient` | 인스턴스 직접 접근 (read 메서드 등)                 |
-| `isPending` | `boolean`            | `submit` / `del` / `query` 진행 중 여부             |
-| `error`     | `Error \| null`      | 마지막 mutation 에러. 성공 또는 `reset()` 시 `null` |
-| `reset`     | `() => void`         | `isPending`, `error` 초기화                         |
-| `submit`    | function             | `client.submit()` 래퍼 — 상태 자동 관리             |
-| `del`       | function             | `client.delete()` 래퍼 — 상태 자동 관리             |
-| `query`     | function             | `client.query()` 래퍼 — 상태 자동 관리              |
-
-#### 예시
-
-```tsx
-import { useEntityServer } from "entity-server-client/react";
-
-function AccountForm() {
-    const { submit, del, isPending, error, reset } = useEntityServer();
-
-    const handleSave = async () => {
-        reset();
-        await submit("account", { name: "홍길동", email: "hong@example.com" });
-    };
-
-    const handleDelete = async (seq: number) => {
-        await del("account", seq);
-    };
-
-    return (
-        <div>
-            {isPending && <span>저장 중...</span>}
-            {error && <span style={{ color: "red" }}>{error.message}</span>}
-            <button onClick={handleSave} disabled={isPending}>
-                저장
-            </button>
-            <button onClick={() => handleDelete(1)} disabled={isPending}>
-                삭제
-            </button>
-        </div>
-    );
-}
-```
-
-토큰을 런타임에 주입하는 경우:
-
-```tsx
-const { submit } = useEntityServer({
-    tokenResolver: () => localStorage.getItem("access_token"),
-});
-```
-
-**페이지 새로고침 후 로그인 상태 + 자동 갱신 복원:**
-
-`resumeSession`에 저장된 refresh_token을 넘기면 마운트 시 `refreshToken()`을 호출해
-새 access_token을 발급받고, `keepSession: true`이면 타이머도 자동 재시작됩니다.
-
-```tsx
-// App.tsx 또는 로그인 복원을 담당하는 컴포넌트
-export function AppShell() {
-    const storedRefreshToken =
-        localStorage.getItem("auth_refresh_token") ?? undefined;
-
-    useEntityServer({
-        resumeSession: storedRefreshToken,
-        keepSession: true,
-        onTokenRefreshed: (accessToken) => {
-            localStorage.setItem("auth_access_token", accessToken);
-        },
-        onSessionExpired: () => {
-            window.location.href = "/login";
-        },
-    });
-
-    return <RouterOutlet />;
-}
-```
-
-> 마운트 시 `resumeSession`이 있으면:
->
-> 1. `refreshToken(storedRefreshToken)` 호출 → 서버에서 새 access_token 발급
-> 2. 패키지 내부 `this.token` 자동 교체
-> 3. `onTokenRefreshed` 콜백 호출
-> 4. `keepSession: true`이면 다음 만료 전 타이머 자동 예약
-> 5. 실패 시 `onSessionExpired` 콜백 호출
-
-컴포넌트별 독립 인스턴스가 필요한 경우:
-
-```tsx
-const { client } = useEntityServer({
-    singleton: false,
-    baseUrl: "https://other-server.example.com",
-});
-```
-
----
-
-## 암호화 패킷 처리
-
-### 자동 복호화
-
-서버 응답이 `Content-Type: application/octet-stream`이면 `request()` 내부에서 자동으로 복호화됩니다.
-XChaCha20-Poly1305 알고리즘을 사용하며, 키는 현재 JWT 토큰의 SHA-256 해시입니다.
-
-별도 처리 없이 일반 응답과 동일하게 사용하면 됩니다.
-
-### `readRequestBody(body, contentType?, requireEncrypted?)`
-
-원시 암호화 payload를 직접 파싱할 때 사용합니다.
-주로 서버 측 미들웨어나 SSR 환경에서 클라이언트로부터 받은 암호화 body를 처리할 때 활용합니다.
-
-```ts
-// 암호화 body 복호화
-const data = client.readRequestBody(
-    arrayBuffer, // ArrayBuffer | Uint8Array
-    "application/octet-stream",
-    true, // requireEncrypted: 암호화 아니면 에러
-);
+## 목차
 
-// 일반 JSON body 파싱
-const data2 = client.readRequestBody(jsonString, "application/json");
-```
+| 구분               | 파일                                         |
+| ------------------ | -------------------------------------------- |
+| import             | [api/import.md](api/import.md)               |
+| 서버 헬스체크      | [api/health.md](api/health.md)               |
+| 인스턴스 생성/설정 | [api/setup.md](api/setup.md)                 |
+| 인증               | [api/auth.md](api/auth.md)                   |
+| 트랜잭션           | [api/transaction.md](api/transaction.md)     |
+| 엔티티 CRUD / 조회 | [api/entity.md](api/entity.md)               |
+| 푸시 관련          | [api/push.md](api/push.md)                   |
+| 이메일 인증 / 변경 | [api/email.md](api/email.md)                 |
+| SMS                | [api/sms.md](api/sms.md)                     |
+| SMTP 메일          | [api/smtp.md](api/smtp.md)                   |
+| 알림톡 / 친구톡    | [api/alimtalk.md](api/alimtalk.md)           |
+| PG 결제            | [api/pg.md](api/pg.md)                       |
+| 파일 스토리지      | [api/file.md](api/file.md)                   |
+| 본인인증           | [api/identity.md](api/identity.md)           |
+| QR코드 / 바코드    | [api/utils.md](api/utils.md)                 |
+| React Hook         | [api/react.md](api/react.md)                 |
+| 암호화 패킷 처리   | [api/packet.md](api/packet.md)               |