entity-server-client 0.1.0

package/src/index.ts

@@ -0,0 +1,597 @@
+// @ts-ignore
+import { xchacha20poly1305 } from "@noble/ciphers/chacha";
+// @ts-ignore
+import { sha256 } from "@noble/hashes/sha2";
+
+/**
+ * 엔티티 목록 조회 파라미터입니다.
+ *
+ * ```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;
+}
+
+/**
+ * `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 packetMagicLen: number;
+    private activeTxId: string | null = null;
+
+    /**
+     * EntityServerClient 인스턴스를 생성합니다.
+     *
+     * 기본값:
+     * - `baseUrl`: `VITE_ENTITY_SERVER_URL` 또는 `http://localhost:47200`
+     * - `packetMagicLen`: `VITE_PACKET_MAGIC_LEN` 또는 `4`
+     */
+    constructor(options: EntityServerClientOptions = {}) {
+        const envBaseUrl = readEnv("VITE_ENTITY_SERVER_URL");
+        const envMagicLen = readEnv("VITE_PACKET_MAGIC_LEN");
+
+        this.baseUrl = (
+            options.baseUrl ??
+            envBaseUrl ??
+            "http://localhost:47200"
+        ).replace(/\/$/, "");
+
+        this.token = options.token ?? "";
+        this.packetMagicLen =
+            options.packetMagicLen ?? (envMagicLen ? Number(envMagicLen) : 4);
+    }
+
+    /** baseUrl, token, packetMagicLen 값을 런타임에 갱신합니다. */
+    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;
+        }
+    }
+
+    /** 인증 요청에 사용할 JWT Access Token을 설정합니다. */
+    setToken(token: string): void {
+        this.token = token;
+    }
+
+    /** 암호화 패킷 magic 길이(`packet_magic_len`)를 설정합니다. */
+    setPacketMagicLen(length: number): void {
+        this.packetMagicLen = length;
+    }
+
+    /** 현재 암호화 패킷 magic 길이를 반환합니다. */
+    getPacketMagicLen(): number {
+        return this.packetMagicLen;
+    }
+
+    /** 로그인 후 `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;
+        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;
+        return data.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}`);
+    }
+
+    /** 페이지네이션/정렬/필터 조건으로 엔티티 목록을 조회합니다. */
+    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 요청 함수입니다.
+     *
+     * 응답이 `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 headers: Record<string, string> = {
+            "Content-Type": "application/json",
+            ...extraHeaders,
+        };
+        if (withAuth && this.token) {
+            headers.Authorization = `Bearer ${this.token}`;
+        }
+
+        const res = await fetch(this.baseUrl + path, {
+            method,
+            headers,
+            ...(body != null ? { body: JSON.stringify(body) } : {}),
+        });
+
+        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;
+    }
+
+    /** 서버의 암호화 패킷을 복호화해 JSON 객체로 변환합니다. */
+    private decryptPacket<T>(buffer: ArrayBuffer): T {
+        const key = sha256(new TextEncoder().encode(this.token));
+        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("&");
+}
+
+export const entityServer = new EntityServerClient();

package/src/react.ts

@@ -0,0 +1 @@
+export * from "./hooks/useEntityServer";

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+    "compilerOptions": {
+        "target": "ES2022",
+        "module": "ESNext",
+        "moduleResolution": "Bundler",
+        "declaration": true,
+        "outDir": "dist",
+        "strict": true,
+        "skipLibCheck": true
+    },
+    "include": [
+        "src"
+    ]
+}