entity-server-client 0.2.4 → 0.2.6

package/dist/types.d.ts

@@ -0,0 +1,329 @@
+/**
+ * 엔티티 목록 조회 파라미터입니다.
+ *
+ * ```ts
+ * client.list("post", {
+ *   page: 1, limit: 10,
+ *   orderBy: "created_time", orderDir: "DESC",
+ *   fields: ["seq", "title", "created_time"],
+ *   conditions: { status: "active" },
+ * });
+ * ```
+ */
+export interface EntityListParams {
+    /** 조회 페이지 번호. 기본값: `1` */
+    page?: number;
+    /** 페이지당 레코드 수. 기본값: `20` */
+    limit?: number;
+    /** 정렬 기준 필드명 */
+    orderBy?: string;
+    /** 정렬 방향. 기본값: `"ASC"` */
+    orderDir?: "ASC" | "DESC";
+    /**
+     * 반환할 필드 목록.
+     *
+     * - **미지정 (기본값)**: 엔티티의 인덱스 필드만 반환합니다.
+     *   복호화를 건너뛰기 때문에 **가장 빠릅니다**.
+     * - `["*"]`: 전체 필드 반환 (복호화 수행).
+     * - 필드명 목록: 해당 필드만 반환합니다.
+     *   엔티티 설정에 `index`로 선언된 필드만 지정 가능합니다.
+     *   존재하지 않는 필드명을 지정하면 서버 에러가 발생합니다.
+     * - `seq`, `created_time`, `updated_time`, `license_seq`는 필드에 관계없이 항상 포함됩니다.
+     *
+     * ```ts
+     * // 기본값 (인덱스 필드만, 가장 빠름)
+     * client.list("account")
+     * // 전체 필드
+     * client.list("account", { fields: ["*"] })
+     * // seq, name, email만
+     * client.list("account", { fields: ["seq", "name", "email"] })
+     * ```
+     */
+    fields?: string[];
+    /** 필터 조건. POST body로 전달됩니다. (예: `{ status: "active" }`) */
+    conditions?: Record<string, unknown>;
+}
+/**
+ * `list()`, `history()` 응답의 `data` 필드 구조입니다.
+ *
+ * 서버는 항상 이 구조로 반환합니다:
+ * ```json
+ * { "ok": true, "data": { "items": [...], "total": 100, "page": 1, "limit": 20 } }
+ * ```
+ */
+export interface EntityListResult<T = unknown> {
+    items: T[];
+    /** 전체 레코드 수 */
+    total: number;
+    /** 현재 페이지 번호 */
+    page: number;
+    /** 페이지당 레코드 수 */
+    limit: number;
+}
+/**
+ * `query()` 메서드에 전달하는 SQL 쿼리 요청입니다.
+ *
+ * - `sql`: SELECT 전용 SQL. 인덱스 테이블만 조회 가능하며 JOIN 지원.
+ * - `params`: SQL 바인딩 파라미터 (`?` 플레이스홀더 대응).
+ * - `limit`: 최대 반환 건수 (최대 1000. 미지정 시 서버 기본값 적용).
+ *
+ * ```ts
+ * client.query("order", {
+ *   sql: `SELECT o.seq, o.status, u.name
+ *         FROM order o
+ *         JOIN account u ON u.data_seq = o.account_seq
+ *         WHERE o.status = ?`,
+ *   params: ["pending"],
+ *   limit: 100,
+ * });
+ * ```
+ */
+export interface EntityQueryRequest {
+    sql: string;
+    params?: unknown[];
+    limit?: number;
+}
+/**
+ * `history()` 응답의 개별 이력 레코드 구조입니다.
+ *
+ * - `action`: `"INSERT"` | `"UPDATE"` | `"DELETE_SOFT"` | `"DELETE_HARD"` | `"ROLLBACK"`
+ * - `data_snapshot`: 변경 당시 엔티티 데이터 스냅샷
+ */
+export interface EntityHistoryRecord<T = unknown> {
+    seq: number;
+    action: "INSERT" | "UPDATE" | "DELETE_SOFT" | "DELETE_HARD" | "ROLLBACK" | string;
+    data_snapshot: T | null;
+    changed_by: number | null;
+    changed_time: string;
+}
+export interface RegisterPushDeviceOptions {
+    platform?: string;
+    deviceType?: string;
+    browser?: string;
+    browserVersion?: string;
+    pushEnabled?: boolean;
+    transactionId?: string;
+}
+/** EntityServerClient 생성/설정 옵션입니다. */
+export interface EntityServerClientOptions {
+    baseUrl?: string;
+    token?: string;
+    /**
+     * `true`이면 인증된 POST/PUT 요청 바디를 XChaCha20-Poly1305로 암호화합니다.
+     *
+     * 서버의 `EnablePacketEncryption`이 활성화된 경우 필수로 설정해야 합니다.
+     * 로그인(`login()`)·토큰 갱신(`refreshToken()`)은 인증 전 요청이므로 자동으로 건너뜁니다.
+     *
+     * 기본값: `false`
+     */
+    encryptRequests?: boolean;
+    /**
+     * `true`이면 `login()` 성공 후 Access Token 만료 전에 자동으로 갱신(silent refresh)합니다.
+     * 갱신 시점은 `expires_in - refreshBuffer` 초입니다.
+     *
+     * 갱신 성공 시 `onTokenRefreshed`, 실패 시 `onSessionExpired` 콜백이 호출됩니다.
+     *
+     * 기본값: `false`
+     */
+    keepSession?: boolean;
+    /**
+     * 만료 몇 초 전에 자동 갱신을 시도할지 설정합니다.
+     *
+     * 예: `expires_in = 3600`, `refreshBuffer = 60` → 3540초 후 갱신
+     *
+     * 기본값: `60`
+     */
+    refreshBuffer?: number;
+    /**
+     * 자동 갱신 성공 시 호출되는 콜백입니다.
+     * 새 `access_token`과 `expires_in`이 전달됩니다.
+     * 앱은 이 콜백에서 localStorage 등에 토큰을 저장해야 합니다.
+     */
+    onTokenRefreshed?: (accessToken: string, expiresIn: number) => void;
+    /**
+     * 세션 유지 갱신 실패 시 호출되는 콜백입니다.
+     * refresh_token 만료 등으로 재발급이 불가능한 경우입니다.
+     * 앱은 이 콜백에서 로그인 페이지로 이동하는 등의 처리를 해야 합니다.
+     */
+    onSessionExpired?: (error: Error) => void;
+    /**
+     * HMAC 인증용 API Key (`X-API-Key` 헤더).
+     * `hmacSecret`과 함께 설정하면 HMAC 인증 모드로 동작합니다.
+     * **서버 사이드(Node.js 등) 전용. 브라우저에서는 사용하지 마세요.**
+     */
+    apiKey?: string;
+    /**
+     * HMAC 인증 시크릿. `apiKey`와 함께 설정하면 HMAC 인증 모드로 동작합니다.
+     *
+     * 패킷 암호화 키도 이 값에서 HKDF-SHA256으로 유도합니다:
+     * `key = HKDF-SHA256(hmac_secret, info="entity-server:packet-encryption", salt="entity-server:hkdf:v1")`
+     *
+     * **서버 사이드(Node.js 등) 전용. 브라우저에서는 사용하지 마세요.**
+     */
+    hmacSecret?: string;
+}
+/** `smtpSend()` 요청 파라미터입니다. */
+export interface SmtpSendRequest {
+    /** provider 식별자 (생략 시 기본 provider 사용) */
+    provider?: string;
+    from?: string;
+    to: string[];
+    cc?: string[];
+    bcc?: string[];
+    subject?: string;
+    body_text?: string;
+    body_html?: string;
+    /** 이메일 템플릿 이름 */
+    template_name?: string;
+    /** 템플릿 변수 */
+    template_data?: Record<string, unknown>;
+    /** 첨부 파일 seq 배열 */
+    attachments?: number[];
+    reply_to?: string;
+    ref_entity?: string;
+    ref_seq?: number;
+}
+/** `smsSend()` 요청 파라미터입니다. */
+export interface SmsSendRequest {
+    provider?: string;
+    sender?: string;
+    /** 수신자 전화번호 (필수) */
+    receiver: string;
+    /** 메시지 내용 (필수) */
+    content: string;
+    /** MMS 제목 (LMS/MMS 전용) */
+    subject?: string;
+    image_url?: string;
+    ref_entity?: string;
+    ref_seq?: number;
+}
+/** `pushSend()` 요청 파라미터 (`POST /v1/push/send`) */
+export interface PushSendRequest {
+    /** 수신 계정 seq 배열 (필수) */
+    account_seqs: number[];
+    title: string;
+    body: string;
+    /** 커스텀 페이로드 */
+    data?: Record<string, string>;
+    ref_entity?: string;
+    ref_seq?: number;
+}
+/** `pushSendAll()` 요청 파라미터 (`POST /v1/push/send-all`) */
+export interface PushSendAllRequest {
+    title: string;
+    body: string;
+    data?: Record<string, string>;
+    ref_entity?: string;
+    ref_seq?: number;
+}
+/** 알림톡 / 친구톡 버튼 */
+export interface AlimtalkButton {
+    name: string;
+    type: string;
+    url_mobile?: string;
+    url_pc?: string;
+}
+/** `alimtalkSend()` 요청 파라미터 */
+export interface AlimtalkSendRequest {
+    /** 알림톡 템플릿 코드 (필수) */
+    template_code: string;
+    /** 수신자 전화번호 (필수) */
+    receiver: string;
+    variables?: Record<string, string>;
+    provider?: string;
+}
+/** `friendtalkSend()` 요청 파라미터 */
+export interface FriendtalkSendRequest {
+    /** 수신자 전화번호 (필수) */
+    receiver: string;
+    /** 메시지 내용 (필수) */
+    content: string;
+    /** 메시지 타입 (`"text"` | `"image"` | `"wide_image"` 등, 기본 `"text"`) */
+    msg_type?: string;
+    image_url?: string;
+    image_link?: string;
+    /** 광고 여부 (기본 `true`) */
+    is_ad?: boolean;
+    buttons?: AlimtalkButton[];
+    carousel_json?: string;
+    items_json?: string;
+    header?: string;
+    provider?: string;
+}
+/** `pgCreateOrder()` 요청 파라미터 */
+export interface PgCreateOrderRequest {
+    /** 결제 금액 (필수) */
+    amount: number;
+    /** 주문명 (필수) */
+    order_name: string;
+    currency?: string;
+    customer_name?: string;
+    customer_email?: string;
+    provider?: string;
+    metadata?: Record<string, unknown>;
+}
+/** `pgConfirmPayment()` 요청 파라미터 */
+export interface PgConfirmPaymentRequest {
+    payment_key: string;
+    order_id: string;
+    amount: number;
+}
+/** `pgCancelPayment()` 요청 파라미터 */
+export interface PgCancelPaymentRequest {
+    /** 취소 사유 (필수) */
+    cancel_reason: string;
+    /** 부분 취소 금액 (생략 시 전액 취소) */
+    cancel_amount?: number;
+    refund_account?: {
+        bank: string;
+        account_number: string;
+        holder_name: string;
+    };
+}
+/** `identityRequest()` 요청 파라미터 */
+export interface IdentityRequestOptions {
+    /** 인증 목적 (필수, 예: `"signup"`, `"password_reset"`) */
+    purpose: string;
+    /** 인증 방법 (예: `"simple"`, `"pass"`) */
+    method?: string;
+    provider?: string;
+}
+/** `qrcode()` / `qrcodeBase64()` / `qrcodeText()` 공통 옵션 */
+export interface QRCodeOptions {
+    /** PNG 크기 픽셀 (기본 256, 최대 2048) */
+    size?: number;
+    /** 오류 복구 수준 (기본 `"medium"`) */
+    error_correction?: "low" | "medium" | "high" | "highest";
+    /** 전경색 hex (기본 `"#000000"`) */
+    fg_color?: string;
+    /** 배경색 hex (기본 `"#ffffff"`) */
+    bg_color?: string;
+}
+/** `barcode()` 옵션 */
+export interface BarcodeOptions {
+    /** 바코드 타입 (기본 `"code128"`) */
+    type?: "code128" | "code39" | "ean13" | "ean8" | "codabar" | "datamatrix" | "itf";
+    /** 너비 픽셀 (기본 300, 최대 2048) */
+    width?: number;
+    /** 높이 픽셀 (기본 100, 최대 2048) */
+    height?: number;
+}
+/** 파일 메타 정보 */
+export interface FileMeta {
+    uuid: string;
+    original_name: string;
+    size: number;
+    mime_type: string;
+    entity: string;
+    ref_seq?: number;
+    is_public?: boolean;
+    created_time: string;
+    url?: string;
+}
+/** `fileUpload()` 옵션 */
+export interface FileUploadOptions {
+    /** 파일에 연결할 ref_seq */
+    refSeq?: number;
+    /** 공개 파일 여부 (기본 서버 설정 따름) */
+    isPublic?: boolean;
+}

package/docs/apis.md

@@ -59,10 +59,10 @@ import { useEntityServer } from "entity-server-client/react";
 **admin-web 예시:**
 
 ```ts
-import { checkServerHealth, entityServer } from "entity-server-client";
+import { entityServer } from "entity-server-client";
 
 // 앱 초기화 시 한 번 실행 (예: App.tsx mount, main.tsx 초기화)
-const health = await checkServerHealth();
+const health = await entityServer.checkHealth();
 // → 서버의 packet_encryption: true 이면
 //   클라이언트의 encryptRequests: true 로 자동 설정됨
 ```
@@ -78,9 +78,8 @@ if (packet_encryption) {
 }
 ```
 
-> **중요:** `packetMagicLen` 값은 클라이언트가 미리 알고 있어야 합니다.
-> 빌드 시점에 `VITE_PACKET_MAGIC_LEN` 환경변수로 결정되며,
-> 서버와 일치해야 올바르게 복호화됩니다.
+> **주의:** 패킷 magic 길이(K)는 `K = 2 + key[31] % 14` 공식으로 패킷 키에서 자동 파생됩니다.
+> 클라이언트와 서버 모두 동일한 패킷 키를 보유하므로 별도 설정 필요 없습니다.
 
 ---
 
@@ -92,7 +91,6 @@ if (packet_encryption) {
 | ------------------ | ---------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `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초 후 갱신                                                                               |
@@ -104,7 +102,6 @@ if (packet_encryption) {
 const client = new EntityServerClient({
     baseUrl: "https://api.example.com",
     token: "eyJhbGciOi...",
-    packetMagicLen: 4,
     encryptRequests: true, // 요청 바디 암호화 활성화
 });
 
@@ -120,17 +117,14 @@ import { entityServer } from "entity-server-client";
 client.configure({
     baseUrl: "https://api.example.com",
     token: "new-access-token",
-    packetMagicLen: 6,
     encryptRequests: true,
 });
 ```
 
-### `setToken(token)` / `setPacketMagicLen(length)` / `getPacketMagicLen()`
+### `setToken(token)`
 
 ```ts
 client.setToken("eyJhbGciOi...");
-client.setPacketMagicLen(4);
-const len = client.getPacketMagicLen(); // 4
 ```
 
 ---
@@ -658,7 +652,6 @@ 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`                           | —      | 세션 유지 활성화 (인덱스 참고)                                                                  |

package/docs/react.md

@@ -12,7 +12,7 @@ import { useEntityServer } from "entity-server-client/react";
 import { useEntityServer } from "entity-server-client/react";
 
 export function AccountPage() {
-  const client = useEntityServer({
+  const { client } = useEntityServer({
     tokenResolver: () => localStorage.getItem("auth_access_token"),
   });
 
@@ -34,7 +34,7 @@ export function AccountPage() {
 - `false`: 훅 호출 스코프마다 새 인스턴스 생성
 
 ```ts
-const client = useEntityServer({
+const { client } = useEntityServer({
     singleton: false,
     baseUrl: "http://localhost:47200",
 });
@@ -45,19 +45,18 @@ const client = useEntityServer({
 렌더 시점에 토큰을 읽어 자동으로 `setToken`을 적용합니다.
 
 ```ts
-const client = useEntityServer({
+const { client } = useEntityServer({
     tokenResolver: () => sessionStorage.getItem("access_token"),
 });
 ```
 
-### `baseUrl`, `token`, `packetMagicLen`
+### `baseUrl`, `token`
 
 `EntityServerClientOptions`와 동일하게 전달할 수 있습니다.
 
 ```ts
-const client = useEntityServer({
+const { client } = useEntityServer({
     baseUrl: import.meta.env.VITE_ENTITY_SERVER_URL,
-    packetMagicLen: Number(import.meta.env.VITE_PACKET_MAGIC_LEN ?? 4),
 });
 ```
 
@@ -68,7 +67,7 @@ import { useQuery } from "@tanstack/react-query";
 import { useEntityServer } from "entity-server-client/react";
 
 export function useAccountList() {
-    const client = useEntityServer({
+    const { client } = useEntityServer({
         tokenResolver: () => localStorage.getItem("auth_access_token"),
     });
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "entity-server-client",
-    "version": "0.2.4",
+    "version": "0.2.6",
     "license": "MIT",
     "type": "module",
     "publishConfig": {
@@ -30,6 +30,7 @@
         "@noble/hashes": "^1.7.2"
     },
     "devDependencies": {
+        "@types/node": "^25.3.3",
         "@types/react": "^19.2.2",
         "esbuild": "^0.25.0",
         "react": "^19.2.0",

package/src/EntityServerClient.ts

@@ -0,0 +1,54 @@
+/**
+ * @file EntityServerClient.ts
+ * Mixin 패턴으로 구성된 EntityServerClient.
+ *
+ * 절(section)별 구현:
+ *   src/client/base.ts      — 상태·생성자·공통 헬퍼
+ *   src/mixins/auth.ts      — 인증 (로그인/로그아웃/2FA/OAuth 등)
+ *   src/mixins/entity.ts    — 트랜잭션 & 엔티티 CRUD
+ *   src/mixins/push.ts      — 푸시 디바이스 관리 & 발송
+ *   src/mixins/email.ts     — 이메일 인증/변경
+ *   src/mixins/sms.ts       — SMS 발송/인증
+ *   src/mixins/smtp.ts      — SMTP 메일 발송
+ *   src/mixins/alimtalk.ts  — 알림톡/친구톡
+ *   src/mixins/pg.ts        — PG 결제 게이트웨이
+ *   src/mixins/file.ts      — 파일 스토리지
+ *   src/mixins/identity.ts  — 본인인증
+ *   src/mixins/utils.ts     — QR코드/바코드
+ */
+import { EntityServerClientBase } from "./client/base";
+import { AuthMixin } from "./mixins/auth";
+import { EntityMixin } from "./mixins/entity";
+import { PushMixin } from "./mixins/push";
+import { EmailMixin } from "./mixins/email";
+import { SmsMixin } from "./mixins/sms";
+import { SmtpMixin } from "./mixins/smtp";
+import { AlimtalkMixin } from "./mixins/alimtalk";
+import { PgMixin } from "./mixins/pg";
+import { FileMixin } from "./mixins/file";
+import { IdentityMixin } from "./mixins/identity";
+import { UtilsMixin } from "./mixins/utils";
+
+// ─── Composed class ───────────────────────────────────────────────────────────
+
+export class EntityServerClient extends UtilsMixin(
+    IdentityMixin(
+        FileMixin(
+            PgMixin(
+                AlimtalkMixin(
+                    SmtpMixin(
+                        SmsMixin(
+                            EmailMixin(
+                                PushMixin(
+                                    EntityMixin(
+                                        AuthMixin(EntityServerClientBase),
+                                    ),
+                                ),
+                            ),
+                        ),
+                    ),
+                ),
+            ),
+        ),
+    ),
+) {}