entity-server-client 0.2.5 → 0.3.0

package/docs/api/entity.md

@@ -0,0 +1,273 @@
+# 엔티티 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);
+```

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,41 @@
+# 서버 헬스체크
+
+## 개요
+
+앱 시작 시 서버의 패킷 암호화 설정을 감지하여 클라이언트 설정을 자동으로 맞춥니다.
+
+**헬스체크 응답:**
+
+```json
+{
+    "ok": true,
+    "packet_encryption": false
+}
+```
+
+## 자동 초기화 (권장)
+
+**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,34 @@
+# 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";
+```

package/docs/api/packet.md

@@ -0,0 +1,25 @@
+# 암호화 패킷 처리
+
+## 자동 복호화
+
+서버 응답이 `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");
+```

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" 등
+```