entity-server-client 0.2.4 → 0.2.5

package/src/index.ts

@@ -1,920 +1,6 @@
-// @ts-ignore
-import { xchacha20poly1305 } from "@noble/ciphers/chacha";
-// @ts-ignore
-import { sha256 } from "@noble/hashes/sha2";
-// @ts-ignore
-import { hkdf } from "@noble/hashes/hkdf";
-// @ts-ignore
-import { hmac } from "@noble/hashes/hmac";
+export * from "./types";
+export * from "./EntityServerClient";
 
-/**
- * 엔티티 목록 조회 파라미터입니다.
- *
- * ```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>;
-}
-
-/**
- * `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;
-}
-
-export interface RegisterPushDeviceOptions {
-    platform?: string;
-    deviceType?: string;
-    browser?: string;
-    browserVersion?: string;
-    pushEnabled?: boolean;
-    transactionId?: string;
-}
-
-/** EntityServerClient 생성/설정 옵션입니다. */
-export interface EntityServerClientOptions {
-    baseUrl?: string;
-    token?: string;
-    packetMagicLen?: number;
-    /**
-     * `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;
-}
-
-/**
- * `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;
-}
-
-/**
- * `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;
-}
-
-/** Vite 환경변수(`import.meta.env`)에서 값을 읽습니다. */
-function readEnv(name: string): string | undefined {
-    const meta = import.meta as unknown as {
-        env?: Record<string, string | undefined>;
-    };
-    return meta?.env?.[name];
-}
-
-export class EntityServerClient {
-    private baseUrl: string;
-    private token: string;
-    private apiKey: string;
-    private hmacSecret: string;
-    private packetMagicLen: number;
-    private encryptRequests: boolean;
-    private activeTxId: string | null = null;
-
-    // 세션 유지 관련
-    private keepSession: boolean;
-    private refreshBuffer: number;
-    private onTokenRefreshed?: (accessToken: string, expiresIn: number) => void;
-    private onSessionExpired?: (error: Error) => void;
-    private _sessionRefreshToken: string | null = null;
-    private _refreshTimer: ReturnType<typeof setTimeout> | null = null;
-
-    /**
-     * EntityServerClient 인스턴스를 생성합니다.
-     *
-     * 기본값:
-     * - `baseUrl`: `VITE_ENTITY_SERVER_URL` 또는 `http://localhost:47200`
-     * - `packetMagicLen`: `VITE_ENTITY_SERVER_PACKET_MAGIC_LEN` 또는 `4`
-     */
-    constructor(options: EntityServerClientOptions = {}) {
-        const envBaseUrl = readEnv("VITE_ENTITY_SERVER_URL");
-        const envMagicLen = readEnv("VITE_ENTITY_SERVER_PACKET_MAGIC_LEN");
-
-        this.baseUrl = (
-            options.baseUrl ??
-            envBaseUrl ??
-            "http://localhost:47200"
-        ).replace(/\/$/, "");
-
-        this.token = options.token ?? "";
-        this.apiKey = options.apiKey ?? "";
-        this.hmacSecret = options.hmacSecret ?? "";
-        this.packetMagicLen =
-            options.packetMagicLen ?? (envMagicLen ? Number(envMagicLen) : 4);
-        this.encryptRequests = options.encryptRequests ?? false;
-        this.keepSession = options.keepSession ?? false;
-        this.refreshBuffer = options.refreshBuffer ?? 60;
-        this.onTokenRefreshed = options.onTokenRefreshed;
-        this.onSessionExpired = options.onSessionExpired;
-    }
-
-    /** baseUrl, token, packetMagicLen, encryptRequests 값을 런타임에 갱신합니다. */
-    configure(options: Partial<EntityServerClientOptions>): void {
-        if (options.baseUrl) {
-            this.baseUrl = options.baseUrl.replace(/\/$/, "");
-        }
-        if (typeof options.token === "string") {
-            this.token = options.token;
-        }
-        if (typeof options.packetMagicLen === "number") {
-            this.packetMagicLen = options.packetMagicLen;
-        }
-        if (typeof options.encryptRequests === "boolean") {
-            this.encryptRequests = options.encryptRequests;
-        }
-        if (typeof options.apiKey === "string") {
-            this.apiKey = options.apiKey;
-        }
-        if (typeof options.hmacSecret === "string") {
-            this.hmacSecret = options.hmacSecret;
-        }
-        if (typeof options.keepSession === "boolean") {
-            this.keepSession = options.keepSession;
-        }
-        if (typeof options.refreshBuffer === "number") {
-            this.refreshBuffer = options.refreshBuffer;
-        }
-        if (options.onTokenRefreshed) {
-            this.onTokenRefreshed = options.onTokenRefreshed;
-        }
-        if (options.onSessionExpired) {
-            this.onSessionExpired = options.onSessionExpired;
-        }
-    }
-
-    /** 인증 요청에 사용할 JWT Access Token을 설정합니다. */
-    setToken(token: string): void {
-        this.token = token;
-    }
-
-    /** HMAC 인증용 API Key를 설정합니다. */
-    setApiKey(apiKey: string): void {
-        this.apiKey = apiKey;
-    }
-
-    /** HMAC 인증용 시크릿을 설정합니다. */
-    setHmacSecret(secret: string): void {
-        this.hmacSecret = secret;
-    }
-
-    /** 암호화 패킷 magic 길이(`packet_magic_len`)를 설정합니다. */
-    setPacketMagicLen(length: number): void {
-        this.packetMagicLen = length;
-    }
-
-    /** 현재 암호화 패킷 magic 길이를 반환합니다. */
-    getPacketMagicLen(): number {
-        return this.packetMagicLen;
-    }
-
-    /**
-     * 자동 토큰 갱신 타이머를 시작합니다.
-     * @param refreshToken 갱신에 사용할 Refresh Token
-     * @param expiresIn Access Token의 유효 기간 (초)
-     */
-    private _scheduleKeepSession(
-        refreshToken: string,
-        expiresIn: number,
-    ): void {
-        this._clearRefreshTimer();
-        this._sessionRefreshToken = refreshToken;
-
-        const delayMs = Math.max((expiresIn - this.refreshBuffer) * 1000, 0);
-        this._refreshTimer = setTimeout(async () => {
-            if (!this._sessionRefreshToken) return;
-            try {
-                const result = await this.refreshToken(
-                    this._sessionRefreshToken,
-                );
-                this.onTokenRefreshed?.(result.access_token, result.expires_in);
-                // 갱신 성공 시 다음 만료 전 타이머 재예약
-                this._scheduleKeepSession(
-                    this._sessionRefreshToken,
-                    result.expires_in,
-                );
-            } catch (err) {
-                this._clearRefreshTimer();
-                this.onSessionExpired?.(
-                    err instanceof Error ? err : new Error(String(err)),
-                );
-            }
-        }, delayMs);
-    }
-
-    /** 자동 갱신 타이머를 정리합니다. */
-    private _clearRefreshTimer(): void {
-        if (this._refreshTimer !== null) {
-            clearTimeout(this._refreshTimer);
-            this._refreshTimer = null;
-        }
-    }
-
-    /**
-     * 세션 유지 타이머를 중지합니다.
-     * `logout()` 호출 시 자동으로 중지되므로 직접 호출이 필요한 경우는 드뭅니다.
-     */
-    stopKeepSession(): void {
-        this._clearRefreshTimer();
-        this._sessionRefreshToken = null;
-    }
-
-    /**
-     * 서버 헬스 체크를 수행하고 패킷 암호화 활성 여부를 자동으로 감지합니다.
-     *
-     * 서버가 `packet_encryption: true`를 응답하면 이후 모든 요청에 암호화가 자동 적용됩니다.
-     * 초기화 직후 또는 로그인 전에 호출하면 암호화 설정을 자동으로 구성할 수 있습니다.
-     *
-     * ```ts
-     * await client.checkHealth();
-     * await client.login(email, password); // 이후 요청은 암호화 자동 적용
-     * ```
-     *
-     * @returns `{ ok: true }` 또는 `{ ok: true, packet_encryption: true }`
-     */
-    async checkHealth(): Promise<{ ok: boolean; packet_encryption?: boolean }> {
-        const res = await fetch(`${this.baseUrl}/v1/health`, {
-            signal: AbortSignal.timeout(3000),
-        });
-        const data = (await res.json()) as {
-            ok: boolean;
-            packet_encryption?: boolean;
-        };
-        if (data.packet_encryption) {
-            this.encryptRequests = true;
-        }
-        return data;
-    }
-
-    /** 로그인 후 `access_token`을 내부 상태에 저장합니다. */
-    async login(
-        email: string,
-        password: string,
-    ): Promise<{
-        access_token: string;
-        refresh_token: string;
-        expires_in: number;
-    }> {
-        const data = await this.request<{
-            data: {
-                access_token: string;
-                refresh_token: string;
-                expires_in: number;
-            };
-        }>("POST", "/v1/auth/login", { email, passwd: password }, false);
-        this.token = data.data.access_token;
-        if (this.keepSession) {
-            this._scheduleKeepSession(
-                data.data.refresh_token,
-                data.data.expires_in,
-            );
-        }
-        return data.data;
-    }
-
-    /** Refresh Token으로 Access Token을 재발급받아 내부 토큰을 교체합니다. */
-    async refreshToken(
-        refreshToken: string,
-    ): Promise<{ access_token: string; expires_in: number }> {
-        const data = await this.request<{
-            data: { access_token: string; expires_in: number };
-        }>("POST", "/v1/auth/refresh", { refresh_token: refreshToken }, false);
-        this.token = data.data.access_token;
-        if (this.keepSession) {
-            this._scheduleKeepSession(refreshToken, data.data.expires_in);
-        }
-        return data.data;
-    }
-
-    /**
-     * 서버에 로그아웃을 요청하고 내부 토큰을 초기화합니다.
-     * refresh_token을 서버에 전달해 무효화합니다.
-     */
-    async logout(refreshToken: string): Promise<{ ok: boolean }> {
-        this.stopKeepSession();
-        const data = await this.request<{ ok: boolean }>(
-            "POST",
-            "/v1/auth/logout",
-            { refresh_token: refreshToken },
-            false,
-        );
-        this.token = "";
-        return data;
-    }
-
-    /** 트랜잭션을 시작하고 활성 트랜잭션 ID를 저장합니다. */
-    async transStart(): Promise<string> {
-        const res = await this.request<{ ok: boolean; transaction_id: string }>(
-            "POST",
-            "/v1/transaction/start",
-            undefined,
-            false,
-        );
-        this.activeTxId = res.transaction_id;
-        return this.activeTxId;
-    }
-
-    /** 활성 트랜잭션(또는 전달된 transactionId)을 롤백합니다. */
-    transRollback(transactionId?: string): Promise<{ ok: boolean }> {
-        const txId = transactionId ?? this.activeTxId;
-        if (!txId) {
-            return Promise.reject(
-                new Error("No active transaction. Call transStart() first."),
-            );
-        }
-        this.activeTxId = null;
-        return this.request("POST", `/v1/transaction/rollback/${txId}`);
-    }
-
-    /** 활성 트랜잭션(또는 전달된 transactionId)을 커밋합니다.
-     *
-     * @returns `results` 배열: commit된 각 작업의 `entity`, `action`, `seq`
-     */
-    transCommit(transactionId?: string): Promise<{
-        ok: boolean;
-        results: Array<{ entity: string; action: string; seq: number }>;
-    }> {
-        const txId = transactionId ?? this.activeTxId;
-        if (!txId) {
-            return Promise.reject(
-                new Error("No active transaction. Call transStart() first."),
-            );
-        }
-        this.activeTxId = null;
-        return this.request("POST", `/v1/transaction/commit/${txId}`);
-    }
-
-    /** 시퀀스 ID로 엔티티 단건을 조회합니다. */
-    get<T = unknown>(
-        entity: string,
-        seq: number,
-        opts: { skipHooks?: boolean } = {},
-    ): Promise<{ ok: boolean; data: T }> {
-        const q = opts.skipHooks ? "?skipHooks=true" : "";
-        return this.request("GET", `/v1/entity/${entity}/${seq}${q}`);
-    }
-
-    /** 조건으로 엔티티 단건을 조회합니다. data 컬럼을 완전히 복호화하여 반환합니다. */
-    find<T = unknown>(
-        entity: string,
-        conditions?: Record<string, unknown>,
-        opts: { skipHooks?: boolean } = {},
-    ): Promise<{ ok: boolean; data: T }> {
-        const q = opts.skipHooks ? "?skipHooks=true" : "";
-        return this.request(
-            "POST",
-            `/v1/entity/${entity}/find${q}`,
-            conditions ?? {},
-        );
-    }
-
-    /** 페이지네이션/정렬/필터 조건으로 엔티티 목록을 조회합니다. */
-    list<T = unknown>(
-        entity: string,
-        params: EntityListParams = {},
-    ): Promise<{ ok: boolean; data: EntityListResult<T> }> {
-        const { conditions, fields, orderDir, orderBy, ...rest } = params;
-
-        const queryObj: Record<string, unknown> = {
-            page: 1,
-            limit: 20,
-            ...rest,
-        };
-        if (orderBy) {
-            queryObj.orderBy = orderDir === "DESC" ? `-${orderBy}` : orderBy;
-        }
-        if (fields?.length) {
-            queryObj.fields = fields.join(",");
-        }
-
-        const q = buildQuery(queryObj);
-        return this.request(
-            "POST",
-            `/v1/entity/${entity}/list?${q}`,
-            conditions ?? {},
-        );
-    }
-
-    /**
-     * 엔티티 총 건수를 조회합니다.
-     *
-     * @param conditions 필터 조건 (예: `{ status: "active" }`)
-     */
-    count(
-        entity: string,
-        conditions?: Record<string, unknown>,
-    ): Promise<{ ok: boolean; count: number }> {
-        return this.request(
-            "POST",
-            `/v1/entity/${entity}/count`,
-            conditions ?? {},
-        );
-    }
-
-    /**
-     * 커스텀 SQL로 엔티티를 조회합니다.
-     *
-     * SELECT 전용이며 인덱스 테이블만 조회 가능합니다.
-     * JOIN을 사용해 여러 엔티티를 조합할 수 있습니다.
-     * `entity`는 SQL에 포함된 기본 엔티티명(라우트 경로용)입니다.
-     */
-    query<T = unknown>(
-        entity: string,
-        req: EntityQueryRequest,
-    ): Promise<{ ok: boolean; data: { items: T[]; count: number } }> {
-        return this.request("POST", `/v1/entity/${entity}/query`, req);
-    }
-
-    /** 엔티티 데이터를 생성/수정(Submit)합니다. `seq`가 없으면 INSERT, 있으면 UPDATE입니다. */
-    submit(
-        entity: string,
-        data: Record<string, unknown>,
-        opts: { transactionId?: string; skipHooks?: boolean } = {},
-    ): Promise<{ ok: boolean; seq: number }> {
-        const txId = opts.transactionId ?? this.activeTxId;
-        const extraHeaders = txId ? { "X-Transaction-ID": txId } : undefined;
-        const q = opts.skipHooks ? "?skipHooks=true" : "";
-
-        return this.request(
-            "POST",
-            `/v1/entity/${entity}/submit${q}`,
-            data,
-            true,
-            extraHeaders,
-        );
-    }
-
-    /** 시퀀스 ID로 엔티티를 삭제합니다(`hard=true`면 하드 삭제, 기본은 소프트 삭제). */
-    delete(
-        entity: string,
-        seq: number,
-        opts: {
-            transactionId?: string;
-            hard?: boolean;
-            skipHooks?: boolean;
-        } = {},
-    ): Promise<{ ok: boolean; deleted: number }> {
-        const params = new URLSearchParams();
-        if (opts.hard) params.set("hard", "true");
-        if (opts.skipHooks) params.set("skipHooks", "true");
-        const q = params.size ? `?${params}` : "";
-        const txId = opts.transactionId ?? this.activeTxId;
-        const extraHeaders = txId ? { "X-Transaction-ID": txId } : undefined;
-
-        return this.request(
-            "POST",
-            `/v1/entity/${entity}/delete/${seq}${q}`,
-            undefined,
-            true,
-            extraHeaders,
-        );
-    }
-
-    /** 엔티티 단건의 변경 이력을 조회합니다. 이력 항목당 `action`, `data_snapshot`, `changed_by`, `changed_time`을 포함합니다. */
-    history<T = unknown>(
-        entity: string,
-        seq: number,
-        params: Pick<EntityListParams, "page" | "limit"> = {},
-    ): Promise<{
-        ok: boolean;
-        data: EntityListResult<EntityHistoryRecord<T>>;
-    }> {
-        const q = buildQuery({ page: 1, limit: 50, ...params });
-        return this.request("GET", `/v1/entity/${entity}/history/${seq}?${q}`);
-    }
-
-    /** 특정 이력 시점으로 엔티티를 롤백합니다. */
-    rollback(entity: string, historySeq: number): Promise<{ ok: boolean }> {
-        return this.request(
-            "POST",
-            `/v1/entity/${entity}/rollback/${historySeq}`,
-        );
-    }
-
-    /** 푸시 관련 엔티티로 payload를 전송(Submit)합니다. */
-    push(
-        pushEntity: string,
-        payload: Record<string, unknown>,
-        opts: { transactionId?: string } = {},
-    ): Promise<{ ok: boolean; seq: number }> {
-        return this.submit(pushEntity, payload, opts);
-    }
-
-    /** 푸시 로그 엔티티 목록을 조회합니다. */
-    pushLogList<T = unknown>(
-        params: EntityListParams = {},
-    ): Promise<{ ok: boolean; data: EntityListResult<T> }> {
-        return this.list<T>("push_log", params);
-    }
-
-    /** 계정의 푸시 디바이스를 등록합니다. */
-    registerPushDevice(
-        accountSeq: number,
-        deviceId: string,
-        pushToken: string,
-        opts: RegisterPushDeviceOptions = {},
-    ): Promise<{ ok: boolean; seq: number }> {
-        const {
-            platform,
-            deviceType,
-            browser,
-            browserVersion,
-            pushEnabled = true,
-            transactionId,
-        } = opts;
-
-        return this.submit(
-            "account_device",
-            {
-                id: deviceId,
-                account_seq: accountSeq,
-                push_token: pushToken,
-                push_enabled: pushEnabled,
-                ...(platform ? { platform } : {}),
-                ...(deviceType ? { device_type: deviceType } : {}),
-                ...(browser ? { browser } : {}),
-                ...(browserVersion ? { browser_version: browserVersion } : {}),
-            },
-            { transactionId },
-        );
-    }
-
-    /** 디바이스 레코드의 푸시 토큰을 갱신합니다. */
-    updatePushDeviceToken(
-        deviceSeq: number,
-        pushToken: string,
-        opts: { pushEnabled?: boolean; transactionId?: string } = {},
-    ): Promise<{ ok: boolean; seq: number }> {
-        const { pushEnabled = true, transactionId } = opts;
-        return this.submit(
-            "account_device",
-            {
-                seq: deviceSeq,
-                push_token: pushToken,
-                push_enabled: pushEnabled,
-            },
-            { transactionId },
-        );
-    }
-
-    /** 디바이스의 푸시 수신을 비활성화합니다. */
-    disablePushDevice(
-        deviceSeq: number,
-        opts: { transactionId?: string } = {},
-    ): Promise<{ ok: boolean; seq: number }> {
-        return this.submit(
-            "account_device",
-            {
-                seq: deviceSeq,
-                push_enabled: false,
-            },
-            { transactionId: opts.transactionId },
-        );
-    }
-
-    /**
-     * 요청 바디를 파싱하고 `application/octet-stream`인 경우 복호화합니다.
-     *
-     * 원시 암호화 payload를 직접 다루는 클라이언트에서 사용합니다.
-     */
-    readRequestBody<T = Record<string, unknown>>(
-        body: ArrayBuffer | Uint8Array | string | T | null | undefined,
-        contentType = "application/json",
-        requireEncrypted = false,
-    ): T {
-        const lowered = contentType.toLowerCase();
-        const isEncrypted = lowered.includes("application/octet-stream");
-
-        if (requireEncrypted && !isEncrypted) {
-            throw new Error(
-                "Encrypted request required: Content-Type must be application/octet-stream",
-            );
-        }
-
-        if (isEncrypted) {
-            if (body == null) {
-                throw new Error("Encrypted request body is empty");
-            }
-            if (body instanceof ArrayBuffer) {
-                return this.decryptPacket<T>(body);
-            }
-            if (body instanceof Uint8Array) {
-                const sliced = body.buffer.slice(
-                    body.byteOffset,
-                    body.byteOffset + body.byteLength,
-                );
-                return this.decryptPacket<T>(sliced as ArrayBuffer);
-            }
-            throw new Error(
-                "Encrypted request body must be ArrayBuffer or Uint8Array",
-            );
-        }
-
-        if (body == null || body === "") return {} as T;
-        if (typeof body === "string") return JSON.parse(body) as T;
-        return body as T;
-    }
-
-    /**
-     * 공통 HTTP 요청 함수입니다.
-     *
-     * - `encryptRequests`가 활성화된 인증 요청의 POST 바디를 자동 암호화합니다.
-     * - 응답이 `application/octet-stream`이면 자동 복호화합니다.
-     * - JSON 응답의 `ok`가 false이면 에러를 던집니다.
-     */
-    private async request<T>(
-        method: string,
-        path: string,
-        body?: unknown,
-        withAuth = true,
-        extraHeaders: Record<string, string> = {},
-    ): Promise<T> {
-        const isHmacMode = withAuth && !!(this.apiKey && this.hmacSecret);
-        const headers: Record<string, string> = {
-            "Content-Type": "application/json",
-            ...extraHeaders,
-        };
-        if (!isHmacMode && withAuth && this.token) {
-            headers.Authorization = `Bearer ${this.token}`;
-        }
-
-        // 요청 바디 결정: encryptRequests 활성화 시 POST 바디를 암호화합니다.
-        // - 로그인/토큰 갱신(withAuth=false)은 암호화하지 않습니다.
-        // - GET 은 바디가 없으므로 건너뜁니다.
-        // - HMAC 모드는 token 없이도 hmacSecret 이 있으면 암호화합니다.
-        let fetchBody: string | Uint8Array | null = null;
-        if (body != null) {
-            const shouldEncrypt =
-                this.encryptRequests &&
-                withAuth &&
-                (this.token || isHmacMode) &&
-                method !== "GET" &&
-                method !== "HEAD";
-
-            if (shouldEncrypt) {
-                const plaintext = new TextEncoder().encode(
-                    JSON.stringify(body),
-                );
-                const encrypted = this.encryptPacket(plaintext);
-                headers["Content-Type"] = "application/octet-stream";
-                fetchBody = encrypted;
-            } else {
-                fetchBody = JSON.stringify(body);
-            }
-        }
-
-        // HMAC 모드: X-API-Key / X-Timestamp / X-Nonce / X-Signature 헤더 추가
-        if (isHmacMode) {
-            const timestamp = String(Math.floor(Date.now() / 1000));
-            const nonce = crypto.randomUUID();
-            const bodyBytes =
-                fetchBody instanceof Uint8Array
-                    ? fetchBody
-                    : typeof fetchBody === "string"
-                      ? new TextEncoder().encode(fetchBody)
-                      : new Uint8Array(0);
-            const prefix = new TextEncoder().encode(
-                `${method}|${path}|${timestamp}|${nonce}|`,
-            );
-            const payload = new Uint8Array(prefix.length + bodyBytes.length);
-            payload.set(prefix, 0);
-            payload.set(bodyBytes, prefix.length);
-            const sig = hmac(
-                sha256,
-                new TextEncoder().encode(this.hmacSecret),
-                payload,
-            );
-            const signature = [...sig]
-                .map((b) => b.toString(16).padStart(2, "0"))
-                .join("");
-            headers["X-API-Key"] = this.apiKey;
-            headers["X-Timestamp"] = timestamp;
-            headers["X-Nonce"] = nonce;
-            headers["X-Signature"] = signature;
-        }
-
-        const res = await fetch(this.baseUrl + path, {
-            method,
-            headers,
-            ...(fetchBody != null ? { body: fetchBody as BodyInit } : {}),
-        });
-
-        const contentType = res.headers.get("Content-Type") ?? "";
-
-        if (contentType.includes("application/octet-stream")) {
-            const buffer = await res.arrayBuffer();
-            return this.decryptPacket<T>(buffer);
-        }
-
-        const data = await res.json();
-        if (!data.ok) {
-            const err = new Error(
-                data.message ?? `EntityServer error (HTTP ${res.status})`,
-            );
-            (err as { status?: number }).status = res.status;
-            throw err;
-        }
-        return data as T;
-    }
-
-    /**
-     * 패킷 암호화 키를 유도합니다.
-     * - HMAC 모드 (`hmacSecret` 설정 시): HKDF-SHA256(hmac_secret, "entity-server:packet-encryption")
-     * - JWT 모드: sha256(jwt_token)
-     */
-    private derivePacketKey(): Uint8Array {
-        if (this.hmacSecret) {
-            const salt = new TextEncoder().encode("entity-server:hkdf:v1");
-            const info = new TextEncoder().encode(
-                "entity-server:packet-encryption",
-            );
-            return hkdf(
-                sha256,
-                new TextEncoder().encode(this.hmacSecret),
-                salt,
-                info,
-                32,
-            );
-        }
-        return sha256(new TextEncoder().encode(this.token));
-    }
-
-    /**
-     * 평문 바이트를 XChaCha20-Poly1305로 암호화합니다.
-     * 포맷: [random_magic:packetMagicLen][random_nonce:24][ciphertext+tag]
-     */
-    private encryptPacket(plaintext: Uint8Array): Uint8Array {
-        const key = this.derivePacketKey();
-        const magic = new Uint8Array(this.packetMagicLen);
-        const nonce = new Uint8Array(24);
-        crypto.getRandomValues(magic);
-        crypto.getRandomValues(nonce);
-        const cipher = xchacha20poly1305(key, nonce);
-        const ciphertext = cipher.encrypt(plaintext);
-        const result = new Uint8Array(
-            this.packetMagicLen + 24 + ciphertext.length,
-        );
-        result.set(magic, 0);
-        result.set(nonce, this.packetMagicLen);
-        result.set(ciphertext, this.packetMagicLen + 24);
-        return result;
-    }
-
-    /** 서버의 암호화 패킷을 복호화해 JSON 객체로 변환합니다. */
-    private decryptPacket<T>(buffer: ArrayBuffer): T {
-        const key = this.derivePacketKey();
-        const data = new Uint8Array(buffer);
-
-        if (data.length < this.packetMagicLen + 24 + 16) {
-            throw new Error("Encrypted packet too short");
-        }
-
-        const nonce = data.slice(this.packetMagicLen, this.packetMagicLen + 24);
-        const ciphertext = data.slice(this.packetMagicLen + 24);
-        const cipher = xchacha20poly1305(key, nonce);
-        const plaintext = cipher.decrypt(ciphertext);
-        return JSON.parse(new TextDecoder().decode(plaintext)) as T;
-    }
-}
-
-/** 쿼리 파라미터 객체를 URL 쿼리 문자열로 변환합니다. */
-function buildQuery(params: Record<string, unknown>): string {
-    return Object.entries(params)
-        .filter(([, value]) => value != null)
-        .map(
-            ([key, value]) =>
-                `${encodeURIComponent(key === "orderBy" ? "order_by" : key)}=${encodeURIComponent(String(value))}`,
-        )
-        .join("&");
-}
+import { EntityServerClient } from "./EntityServerClient";
 
 export const entityServer = new EntityServerClient();