entity-server-client 0.1.0

package/docs/apis.md

@@ -0,0 +1,505 @@
+# 함수별 사용법
+
+## 목차
+
+| 구분               | 바로가기                                 |
+| ------------------ | ---------------------------------------- |
+| import             | [import](#import)                        |
+| 인스턴스 생성/설정 | [인스턴스 생성/설정](#인스턴스-생성설정) |
+| 인증               | [인증](#인증)                            |
+| 트랜잭션           | [트랜잭션](#트랜잭션)                    |
+| 엔티티 CRUD / 조회 | [엔티티 CRUD / 조회](#엔티티-crud--조회) |
+| 푸시 관련          | [푸시 관련](#푸시-관련)                  |
+| 암호화 패킷 처리   | [암호화 패킷 처리](#암호화-패킷-처리)    |
+
+---
+
+## 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";
+```
+
+---
+
+## 인스턴스 생성/설정
+
+### `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 바이트 길이 |
+
+```ts
+// 직접 생성
+const client = new EntityServerClient({
+    baseUrl: "https://api.example.com",
+    token: "eyJhbGciOi...",
+    packetMagicLen: 4,
+});
+
+// 싱글톤 (환경변수 자동 읽기)
+import { entityServer } from "entity-server-client";
+```
+
+### `configure(options)`
+
+런타임에 설정을 갱신합니다.
+
+```ts
+client.configure({
+    baseUrl: "https://api.example.com",
+    token: "new-access-token",
+    packetMagicLen: 6,
+});
+```
+
+### `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을 재발급받습니다. 성공 시 내부 토큰이 자동 교체됩니다.
+
+```ts
+const result = await client.refreshToken(auth.refresh_token);
+// result.access_token
+// result.expires_in
+```
+
+---
+
+## 트랜잭션
+
+여러 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 타입 객체
+```
+
+---
+
+### `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);
+```
+
+---
+
+## 암호화 패킷 처리
+
+### 자동 복호화
+
+서버 응답이 `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/react.md

@@ -0,0 +1,80 @@
+# React 전용 가이드
+
+## import
+
+```ts
+import { useEntityServer } from "entity-server-client/react";
+```
+
+## 기본 사용
+
+```ts
+import { useEntityServer } from "entity-server-client/react";
+
+export function AccountPage() {
+  const client = useEntityServer({
+    tokenResolver: () => localStorage.getItem("auth_access_token"),
+  });
+
+  // 예: 버튼 클릭 시 목록 조회
+  const onClick = async () => {
+    const res = await client.list("account", { page: 1, limit: 20 });
+    console.log(res.data);
+  };
+
+  return <button onClick={onClick}>불러오기</button>;
+}
+```
+
+## 옵션
+
+### `singleton` (기본: `true`)
+
+- `true`: 패키지 전역 인스턴스(`entityServer`)를 사용
+- `false`: 훅 호출 스코프마다 새 인스턴스 생성
+
+```ts
+const client = useEntityServer({
+    singleton: false,
+    baseUrl: "http://localhost:47200",
+});
+```
+
+### `tokenResolver`
+
+렌더 시점에 토큰을 읽어 자동으로 `setToken`을 적용합니다.
+
+```ts
+const client = useEntityServer({
+    tokenResolver: () => sessionStorage.getItem("access_token"),
+});
+```
+
+### `baseUrl`, `token`, `packetMagicLen`
+
+`EntityServerClientOptions`와 동일하게 전달할 수 있습니다.
+
+```ts
+const client = useEntityServer({
+    baseUrl: import.meta.env.VITE_ENTITY_SERVER_URL,
+    packetMagicLen: Number(import.meta.env.VITE_PACKET_MAGIC_LEN ?? 4),
+});
+```
+
+## React Query와 함께 사용 예시
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+import { useEntityServer } from "entity-server-client/react";
+
+export function useAccountList() {
+    const client = useEntityServer({
+        tokenResolver: () => localStorage.getItem("auth_access_token"),
+    });
+
+    return useQuery({
+        queryKey: ["account", "list"],
+        queryFn: () => client.list("account", { page: 1, limit: 20 }),
+    });
+}
+```

package/package.json

@@ -0,0 +1,38 @@
+{
+    "name": "entity-server-client",
+    "version": "0.1.0",
+    "license": "MIT",
+    "type": "module",
+    "publishConfig": {
+        "access": "public"
+    },
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        },
+        "./react": {
+            "types": "./dist/react.d.ts",
+            "default": "./dist/react.js"
+        }
+    },
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "scripts": {
+        "build": "tsc --declaration --emitDeclarationOnly && node build.mjs",
+        "prepublishOnly": "npm run build"
+    },
+    "peerDependencies": {
+        "react": ">=18"
+    },
+    "dependencies": {
+        "@noble/ciphers": "^1.3.0",
+        "@noble/hashes": "^1.7.2"
+    },
+    "devDependencies": {
+        "@types/react": "^19.2.2",
+        "esbuild": "^0.25.0",
+        "react": "^19.2.0",
+        "typescript": "^5.9.3"
+    }
+}

package/src/hooks/useEntityServer.ts

@@ -0,0 +1,50 @@
+import { useMemo } from "react";
+import {
+    EntityServerClient,
+    entityServer,
+    type EntityServerClientOptions,
+} from "../index";
+
+export interface UseEntityServerOptions extends EntityServerClientOptions {
+    singleton?: boolean;
+    tokenResolver?: () => string | undefined | null;
+}
+
+/**
+ * React 환경에서 EntityServerClient 인스턴스를 반환합니다.
+ *
+ * - `singleton=true`(기본): 패키지 전역 `entityServer` 인스턴스를 반환합니다.
+ * - `singleton=false`: 컴포넌트 스코프의 새 인스턴스를 생성합니다.
+ */
+export function useEntityServer(
+    options: UseEntityServerOptions = {},
+): EntityServerClient {
+    const {
+        singleton = true,
+        tokenResolver,
+        baseUrl,
+        packetMagicLen,
+        token,
+    } = options;
+
+    return useMemo(() => {
+        const client = singleton
+            ? entityServer
+            : new EntityServerClient({
+                  baseUrl,
+                  packetMagicLen,
+                  token,
+              });
+
+        if (singleton) {
+            client.configure({ baseUrl, packetMagicLen, token });
+        }
+
+        const resolvedToken = tokenResolver?.();
+        if (typeof resolvedToken === "string") {
+            client.setToken(resolvedToken);
+        }
+
+        return client;
+    }, [singleton, tokenResolver, baseUrl, packetMagicLen, token]);
+}