entity-server-client 0.2.6 → 0.3.1

package/docs/api/file.md

@@ -0,0 +1,80 @@
+# 파일 스토리지
+
+## `fileUpload(entity, file, opts?)`
+
+파일을 업로드합니다 (multipart/form-data). `entity`는 파일이 귀속될 엔티티명입니다.
+
+| 옵션       | 타입      | 설명                                      |
+| ---------- | --------- | ----------------------------------------- |
+| `refSeq`   | `number`  | 연결할 엔티티 레코드 seq                  |
+| `isPublic` | `boolean` | `true`이면 인증 없이 URL로 직접 접근 가능 |
+
+```ts
+const input = document.querySelector('input[type="file"]') as HTMLInputElement;
+const file = input.files![0];
+
+const res = await client.fileUpload("product", file, {
+    refSeq: 10,
+    isPublic: false,
+});
+res.uuid; // 파일 고유 UUID
+res.data; // FileMeta 객체
+res.data.name; // 원본 파일명
+res.data.size; // 파일 크기 (bytes)
+res.data.mime; // MIME 타입
+```
+
+## `fileDownload(entity, uuid)`
+
+파일을 다운로드합니다. `ArrayBuffer`를 반환합니다.
+
+```ts
+const buf = await client.fileDownload("product", "uuid-here");
+const blob = new Blob([buf], { type: "image/png" });
+const url = URL.createObjectURL(blob);
+```
+
+## `fileDelete(entity, uuid)`
+
+파일을 삭제합니다.
+
+```ts
+await client.fileDelete("product", "uuid-here");
+```
+
+## `fileList(entity, opts?)`
+
+엔티티에 연결된 파일 목록을 조회합니다.
+
+```ts
+const res = await client.fileList("product", { refSeq: 10 });
+res.data.items; // FileMeta[]
+res.data.total; // 전체 건수
+```
+
+## `fileMeta(entity, uuid)`
+
+파일 메타 정보를 조회합니다.
+
+```ts
+const res = await client.fileMeta("product", "uuid-here");
+res.data; // FileMeta
+```
+
+## `fileToken(uuid)`
+
+임시 파일 접근 토큰을 발급합니다. 비공개 파일을 일시적으로 공유할 때 사용합니다.
+
+```ts
+const res = await client.fileToken("uuid-here");
+const tempUrl = `${baseUrl}/v1/files/${res.token}`;
+```
+
+## `fileUrl(uuid)`
+
+파일 직접 접근 URL을 반환합니다. (fetch 없음, URL 조합만)
+
+```ts
+const url = client.fileUrl("uuid-here");
+// → "http://localhost:47200/v1/files/uuid-here"
+```

package/docs/api/health.md

@@ -0,0 +1,47 @@
+# 서버 헬스체크
+
+## 개요
+
+앱 시작 시 서버의 패킷 암호화 설정을 감지하여 클라이언트 설정을 자동으로 맞춥니다.
+
+**헬스체크 응답:**
+
+```json
+{
+    "ok": true,
+    "packet_encryption": true,
+    "packet_mode": "anonymous",
+    "packet_token": "anon.v1...."
+}
+```
+
+- `packet_encryption`: 서버가 패킷 암호화를 요구하는지 여부
+- `packet_mode`: `"jwt"` (JWT 인증) 또는 `"anonymous"` (익명 토큰)
+- `packet_token`: `anonymous` 모드일 때 포함. `checkHealth()` 호출 시 클라이언트 내부 `anonymousPacketToken`에 **자동 저장**됨
+
+## 자동 초기화 (권장)
+
+**admin-web 예시:**
+
+```ts
+import { entityServer } from "entity-server-client";
+
+// 앱 초기화 시 한 번 실행 (예: App.tsx mount, main.tsx 초기화)
+const health = await entityServer.checkHealth();
+// → 서버의 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 });
+}
+```
+
+> **주의:** 패킷 magic 길이(K)는 `K = 2 + key[31] % 14` 공식으로 패킷 키에서 자동 파생됩니다.
+> 클라이언트와 서버 모두 동일한 패킷 키를 보유하므로 별도 설정 필요 없습니다.

package/docs/api/identity.md

@@ -0,0 +1,32 @@
+# 본인인증
+
+## `identityRequest(opts)`
+
+본인인증 세션을 생성합니다.
+
+```ts
+const res = await client.identityRequest({
+    redirect_url: "https://example.com/identity/callback",
+    method: "pass",
+});
+res.data; // { request_id: "...", auth_url: "..." } 등
+```
+
+## `identityResult(requestId)`
+
+본인인증 결과를 조회합니다. 콜백 처리 후 호출합니다.
+
+```ts
+const res = await client.identityResult("request-id-here");
+res.data; // { name, phone, birth, gender, di, ci, ... }
+```
+
+## `identityVerifyCI(ciHash)`
+
+CI(연계정보) 해시로 기존 계정 중복 여부를 확인합니다.
+
+```ts
+const res = await client.identityVerifyCI("ci-hash-string");
+res.data.exists; // true: 이미 가입된 계정 존재
+res.data.account_seq; // 존재할 경우 해당 계정 seq
+```

package/docs/api/import.md

@@ -0,0 +1,45 @@
+# import
+
+```ts
+import {
+    EntityServerClient,
+    entityServer,
+    type EntityListParams,
+    type EntityListResult,
+    type EntityHistoryRecord,
+    type EntityQueryRequest,
+    type EntityServerClientOptions,
+    type RegisterPushDeviceOptions,
+    type PushSendRequest,
+    type PushSendAllRequest,
+    type SmsSendRequest,
+    type SmtpSendRequest,
+    type AlimtalkSendRequest,
+    type FriendtalkSendRequest,
+    type PgCreateOrderRequest,
+    type PgConfirmPaymentRequest,
+    type PgCancelPaymentRequest,
+    type FileMeta,
+    type FileUploadOptions,
+    type IdentityRequestOptions,
+    type QRCodeOptions,
+    type BarcodeOptions,
+} from "entity-server-client";
+```
+
+React Hook:
+
+```ts
+import { useEntityServer } from "entity-server-client/react";
+```
+
+패킷 프로토콜 코어 (SDK 없이 암복호만 필요할 때):
+
+```ts
+import {
+    derivePacketKey,
+    packetMagicLenFromKey,
+    encryptPacket,
+    decryptPacket,
+} from "entity-server-client/packet";
+```

package/docs/api/packet.md

@@ -0,0 +1,90 @@
+# 암호화 패킷 처리
+
+## 자동 복호화
+
+서버 응답이 `Content-Type: application/octet-stream`이면 `request()` 내부에서 자동으로 복호화됩니다.
+XChaCha20-Poly1305 알고리즘을 사용하며, 키는 HKDF-SHA256으로 파생됩니다.
+
+- 키 소스: `hmacSecret` → `token`(JWT) → `anonymousPacketToken` 순서로 결정
+- salt: `entity-server:hkdf:v1`
+- info: `entity-server:packet-encryption`
+- 출력: 32바이트
+
+별도 처리 없이 일반 응답과 동일하게 사용하면 됩니다.
+
+## `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");
+```
+
+## `entity-server-client/packet` 서브패스 — 프로토콜 코어
+
+패킷 암복호 프로토콜만 독립적으로 사용할 때는 서브패스를 import합니다.
+브라우저, Node.js, 중간 계층 서버 등 SDK 전체가 불필요한 환경에서 유용합니다.
+
+```ts
+import {
+    derivePacketKey,
+    packetMagicLenFromKey,
+    encryptPacket,
+    decryptPacket,
+    PACKET_KEY_SIZE,
+    PACKET_MAGIC_MIN,
+    PACKET_MAGIC_RANGE,
+    PACKET_NONCE_SIZE,
+    PACKET_TAG_SIZE,
+    PACKET_HKDF_SALT,
+    PACKET_INFO_LABEL,
+} from "entity-server-client/packet";
+```
+
+### `derivePacketKey(source, infoLabel?)`
+
+HKDF-SHA256으로 32바이트 패킷 키를 파생합니다.
+
+```ts
+const key = derivePacketKey("anon.v1.example-token");
+// infoLabel 기본값: "entity-server:packet-encryption"
+```
+
+### `packetMagicLenFromKey(key, magicMin?, magicRange?)`
+
+키에서 magic 바이트 길이를 파생합니다. `magicLen = magicMin + key[31] % magicRange`
+
+```ts
+const magicLen = packetMagicLenFromKey(key);
+// 기본값: magicMin=2, magicRange=14 → 결과 범위 [2, 15]
+```
+
+### `encryptPacket(plaintext, key, magicMin?, magicRange?)`
+
+평문 바이트를 XChaCha20-Poly1305로 암호화합니다.
+포맷: `[random_magic:magicLen][random_nonce:24][ciphertext+tag]`
+
+```ts
+const encrypted = encryptPacket(
+    new TextEncoder().encode(JSON.stringify({ ok: true })),
+    key,
+);
+```
+
+### `decryptPacket(buffer, key, magicMin?, magicRange?)`
+
+암호화된 패킷을 복호화해 평문 바이트를 반환합니다.
+
+```ts
+const plaintext = decryptPacket(encrypted, key);
+console.log(new TextDecoder().decode(plaintext));
+```

package/docs/api/pg.md

@@ -0,0 +1,90 @@
+# PG 결제
+
+결제 라이프사이클: `pgCreateOrder` → (사용자 결제 진행) → `pgConfirmPayment` → (`pgSyncPayment` | `pgCancelPayment`)
+
+## `pgCreateOrder(req)`
+
+결제 주문을 생성합니다. 결제 전 서버에 주문 정보를 등록합니다.
+
+| 필드            | 타입     | 설명                    |
+| --------------- | -------- | ----------------------- |
+| `orderId`       | `string` | 가맹점 주문 ID (고유값) |
+| `amount`        | `number` | 결제 금액 (원 단위)     |
+| `orderName`     | `string` | 주문명                  |
+| `customerName`  | `string` | 구매자 이름             |
+| `customerEmail` | `string` | 구매자 이메일           |
+
+```ts
+const order = await client.pgCreateOrder({
+    orderId: "order-2026-001",
+    amount: 15000,
+    orderName: "상품 A",
+    customerName: "홍길동",
+    customerEmail: "hong@example.com",
+});
+order.paymentKey; // 결제창 호출에 필요한 키
+```
+
+## `pgGetOrder(orderId)`
+
+주문 정보를 조회합니다.
+
+```ts
+const order = await client.pgGetOrder("order-2026-001");
+order.status; // "pending" | "paid" | "cancelled" ...
+order.amount;
+order.paymentKey;
+```
+
+## `pgConfirmPayment(req)`
+
+결제 완료 후 서버 측 승인 처리를 합니다. PG사에서 발급된 `paymentKey`와 금액으로 검증합니다.
+
+| 필드         | 타입     | 설명                                   |
+| ------------ | -------- | -------------------------------------- |
+| `paymentKey` | `string` | PG사 결제 키 (클라이언트에서 수신)     |
+| `orderId`    | `string` | 가맹점 주문 ID                         |
+| `amount`     | `number` | 결제 금액 (주문 금액과 불일치 시 에러) |
+
+```ts
+const result = await client.pgConfirmPayment({
+    paymentKey: "toss_paymentKey_abc",
+    orderId: "order-2026-001",
+    amount: 15000,
+});
+result.status; // "paid"
+```
+
+## `pgCancelPayment(paymentKey, req?)`
+
+결제를 취소(환불)합니다.
+
+```ts
+// 전액 취소
+await client.pgCancelPayment("toss_paymentKey_abc");
+
+// 부분 취소
+await client.pgCancelPayment("toss_paymentKey_abc", {
+    cancelReason: "고객 요청",
+    cancelAmount: 5000,
+});
+```
+
+## `pgSyncPayment(paymentKey)`
+
+PG사의 실시간 결제 상태를 서버 DB에 동기화합니다.
+
+```ts
+const result = await client.pgSyncPayment("toss_paymentKey_abc");
+result.status; // 동기화 후 상태
+```
+
+## `pgConfig()`
+
+설정된 PG 정보를 조회합니다. 클라이언트 측 결제창 초기화에 필요한 `clientKey` 등을 포함합니다.
+
+```ts
+const config = await client.pgConfig();
+config.provider; // "toss" | ...
+config.clientKey; // 결제창 초기화용 키
+```

package/docs/api/push.md

@@ -0,0 +1,107 @@
+# 푸시 관련
+
+## `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);
+```
+
+## `pushSend(req)`
+
+특정 계정에 푸시 알림을 직접 발송합니다.
+
+```ts
+const res = await client.pushSend({
+    account_seq: 1,
+    title: "알림 제목",
+    body: "알림 내용",
+});
+res.seq; // 발송 로그 seq
+```
+
+## `pushSendAll(req)`
+
+전체 또는 조건에 맞는 모든 사용자에게 푸시 알림을 발송합니다.
+
+```ts
+const res = await client.pushSendAll({
+    title: "공지사항",
+    body: "전체 공지 내용입니다.",
+});
+res.sent; // 발송 성공 수
+res.failed; // 발송 실패 수
+```
+
+## `pushStatus(seq)`
+
+푸시 발송 로그의 처리 상태를 조회합니다.
+
+```ts
+const res = await client.pushStatus(42);
+res.status; // "sent" | "failed" | "pending" 등
+```

package/docs/api/react.md

@@ -0,0 +1,141 @@
+# 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()` 호출)                                                   |
+| `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` | **모든 API 메서드에 접근 가능한 클라이언트 인스턴스** |
+| `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()` 래퍼 — 상태 자동 관리                |
+
+> **`client`는 `EntityServerClient` 인스턴스 그대로입니다.**  
+> `submit` / `del` / `query` 래퍼는 `isPending` / `error` 상태를 자동 관리해주는 편의 메서드일 뿐이며,  
+> 인증, 푸시, 파일, SMS, PG 등 **모든 API**는 `client.메서드명()`으로 직접 호출합니다.
+
+### `client`로 사용 가능한 모든 API
+
+`client`를 통해 아래 모든 섹션의 메서드를 그대로 사용할 수 있습니다.
+
+| 카테고리           | 주요 메서드 (예시)                                                                 | 상세 문서                        |
+| ------------------ | ---------------------------------------------------------------------------------- | -------------------------------- |
+| 인증               | `login`, `logout`, `register`, `refreshToken`, `oauthLogin`, `enable2FA` …         | [auth.md](auth.md)               |
+| 트랜잭션           | `transStart`, `transCommit`, `transRollback`                                       | [transaction.md](transaction.md) |
+| 엔티티 CRUD / 조회 | `get`, `find`, `list`, `count`, `query`, `submit`, `delete`, `history`, `rollback` | [entity.md](entity.md)           |
+| 푸시               | `pushSend`, `pushSendAll`, `pushStatus`, `registerPushDevice` …                    | [push.md](push.md)               |
+| 이메일 인증        | `emailVerificationSend`, `emailVerificationConfirm`, `emailChange`                 | [email.md](email.md)             |
+| SMS                | `smsSend`, `smsVerificationSend`, `smsVerificationVerify`                          | [sms.md](sms.md)                 |
+| SMTP 메일          | `smtpSend`, `smtpStatus`                                                           | [smtp.md](smtp.md)               |
+| 알림톡 / 친구톡    | `alimtalkSend`, `alimtalkTemplates`, `friendtalkSend`                              | [alimtalk.md](alimtalk.md)       |
+| PG 결제            | `pgCreateOrder`, `pgConfirmPayment`, `pgCancelPayment`, `pgConfig`                 | [pg.md](pg.md)                   |
+| 파일 스토리지      | `fileUpload`, `fileDownload`, `fileDelete`, `fileList`, `fileToken`, `fileUrl`     | [file.md](file.md)               |
+| 본인인증           | `identityRequest`, `identityResult`, `identityVerifyCI`                            | [identity.md](identity.md)       |
+| QR코드 / 바코드    | `qrcode`, `qrcodeBase64`, `barcode`                                                | [utils.md](utils.md)             |
+
+### 기본 사용 예시
+
+```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",
+});
+```